@vizalice/codegraph 1.5.0

package/dist/mcp/explore-session-state.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Session-scoped `codegraph_explore` call state (CG-17).
+ *
+ * What it holds: for ONE MCP session, per project it queried, what explore has
+ * already returned — the files, the line ranges of source inside them, the bytes
+ * they cost, and where in the session each call fell. Nothing else in the server
+ * knows this today: every explore call is answered as if it were the first one,
+ * which is why a 4th call happily re-serves the same spine it already sent
+ * (#1500) and why the tier's call budget can only be *asked* for rather than
+ * enforced. This module is the record those two behaviours are built on
+ * (CG-18 cross-call dedup, CG-19 budget decay). It changes no response itself.
+ *
+ * Four constraints shape the design, all of them from how the daemon actually
+ * runs:
+ *
+ *   1. **Per session, never persisted.** One instance is owned by an
+ *      {@link ../mcp/session.MCPSession} and dies with the socket. A new agent
+ *      session starts clean — dedup across sessions would suppress source the
+ *      new agent has never seen.
+ *   2. **Per project inside the session.** A session can query several projects
+ *      by `projectPath`, so state is keyed by the RESOLVED project root
+ *      (`cg.getProjectRoot()`), not by whatever path the agent typed.
+ *   3. **Bounded.** A long-lived session must not grow without limit, so
+ *      everything is capped — see {@link EXPLORE_SESSION_LIMITS}. Eviction drops
+ *      DETAIL only: `callCount` and `responseBytes` keep counting past it, since
+ *      decay (CG-19) reads the count and must not be reset by its own bound.
+ *   4. **Daemon-safe.** The daemon shares ONE {@link ../mcp/tools.ToolHandler}
+ *      (and a pool of worker threads) across every connected session, so this
+ *      state can live neither on the handler nor in a worker. It lives on the
+ *      session; the handler is handed it per call, and the record of what a call
+ *      emitted travels back on the {@link ToolResult} so it can be recorded on
+ *      the main thread whether dispatch ran in-process or on a worker.
+ *
+ * Over- vs under-reporting: where a bound forces a choice, this module keeps
+ * FEWER ranges than were emitted, never more. A consumer that under-knows
+ * re-serves something the agent already has (wasteful); one that over-knows
+ * withholds source the agent never saw (a Read — the failure this whole area
+ * exists to prevent).
+ */
+/**
+ * Property on a {@link ../mcp/tools.ToolResult} carrying what an explore call
+ * emitted. INTERNAL: `ToolHandler.execute` records it and deletes it before the
+ * result reaches the wire, so the agent-facing response is unchanged. It is a
+ * plain-object property (not a Symbol) on purpose — it has to survive the
+ * structured clone back from a query-pool worker.
+ */
+export declare const EXPLORE_EMISSION_KEY = "_cgExploreEmission";
+/**
+ * Argument key carrying this session's prior-call view INTO a tool call. Same
+ * reasoning as {@link EXPLORE_EMISSION_KEY}: it crosses the worker boundary, so
+ * it must be a serializable property on the args object.
+ */
+export declare const EXPLORE_SESSION_VIEW_ARG = "_cgExploreSession";
+/** An inclusive 1-based line span of a file that was emitted. */
+export interface ExploreLineRange {
+    start: number;
+    end: number;
+}
+/** What one call emitted for one file. */
+export interface ExploreFileEmission {
+    /** Project-relative path, exactly as the response's file header spells it. */
+    path: string;
+    /** Coalesced line spans whose source was in the response. */
+    ranges: ExploreLineRange[];
+    /** Source chars emitted for this file (excludes headers / fences). */
+    bytes: number;
+    /**
+     * Identity of the bytes those ranges were sliced from (CG-18). Cross-call
+     * dedup withholds a span only when the file still hashes to this, so an edit
+     * between two calls re-serves instead of pointing at source the agent holds a
+     * now-wrong copy of. Absent = unprovable, which dedup treats as "re-serve".
+     */
+    fingerprint?: string;
+    /** Set when ranges were dropped to stay under the per-file bound. */
+    rangesTruncated?: boolean;
+}
+/** What one explore call emitted, as reported by the handler. */
+export interface ExploreEmission {
+    /** Resolved project root — the key state is filed under. */
+    projectRoot: string;
+    /** Normalized query text (post `normalizeQuerySpelling`). */
+    query: string;
+    files: ExploreFileEmission[];
+    /** Source chars across all files. */
+    sourceBytes: number;
+    /** Total chars of the response the agent received. */
+    responseBytes: number;
+}
+/** A recorded call: an emission plus where it fell in the session. */
+export interface ExploreCallRecord extends ExploreEmission {
+    /** 1-based call index within this session FOR THIS PROJECT. Survives eviction. */
+    index: number;
+}
+/** Everything the session knows about one project. */
+export interface ExploreProjectState {
+    projectRoot: string;
+    /** Explore calls made this session against this project, including evicted ones. */
+    callCount: number;
+    /** Response chars across every call, including evicted ones. */
+    responseBytes: number;
+    /** Retained call records, oldest first. Bounded — may omit early calls. */
+    calls: ExploreCallRecord[];
+}
+/**
+ * The bounded, serializable read-view handed to a tool call. Deliberately
+ * smaller than the full state: only the most recent calls carry their ranges,
+ * because that is what a dedup/decay decision reads and the whole thing is
+ * structured-cloned to a worker on every call.
+ */
+export interface ExploreSessionView {
+    projects: ExploreProjectState[];
+}
+/**
+ * Memory bounds. Every one of them caps DETAIL; none caps the counters that
+ * CG-19's decay reads.
+ *
+ * Sized against how sessions actually behave: an agent explores one project
+ * (occasionally a second in a monorepo) and the tier call budget is 1–5, so the
+ * retained window covers a whole realistic session and the caps only bite on
+ * pathological ones.
+ */
+export declare const EXPLORE_SESSION_LIMITS: {
+    /** Distinct projects kept per session; least-recently-used evicted first. */
+    readonly MAX_PROJECTS: 4;
+    /** Call records kept per project (oldest dropped; `callCount` keeps counting). */
+    readonly MAX_CALLS_RETAINED: 8;
+    /** Files kept per call — the ones that got the most source. */
+    readonly MAX_FILES_PER_CALL: 24;
+    /** Line ranges kept per file after coalescing — the largest spans. */
+    readonly MAX_RANGES_PER_FILE: 24;
+    /** Most-recent calls per project included in {@link ExploreSessionView}. */
+    readonly MAX_VIEW_CALLS: 4;
+};
+/**
+ * Key a project root is filed under. Resolved so `/repo` and `/repo/` agree;
+ * case-folded on the two platforms whose filesystems are case-insensitive, so a
+ * drive-letter or capitalization difference doesn't split one project in two.
+ */
+export declare function exploreProjectKey(projectRoot: string): string;
+/**
+ * Merge overlapping / adjacent spans into the smallest equivalent set, then cap
+ * it. Adjacency (`next.start <= cur.end + 1`) counts as overlap: two ranges that
+ * touch describe one contiguous block of emitted source.
+ *
+ * When the cap bites, the LARGEST spans are kept and the result is re-sorted by
+ * line so the set still reads top-to-bottom — dropping small fragments loses the
+ * least information, and under-reporting is the safe direction (see the module
+ * header).
+ */
+export declare function coalesceRanges(ranges: ReadonlyArray<ExploreLineRange>, max?: number): {
+    ranges: ExploreLineRange[];
+    truncated: boolean;
+};
+/** Whether a line falls inside any of the (sorted, coalesced) ranges. */
+export declare function rangesCover(ranges: ReadonlyArray<ExploreLineRange>, line: number): boolean;
+/**
+ * One MCP session's explore history. Created per session, thrown away with it.
+ *
+ * Not thread-shared and not a singleton: two sessions on the same daemon own two
+ * instances and can never observe each other's calls. Every method is total —
+ * malformed input is normalized away rather than thrown, because this sits on
+ * the tool-call path and a bookkeeping bug must never fail an explore.
+ */
+export declare class ExploreSessionState {
+    /** Insertion-ordered; a touched project is re-inserted, so the head is the LRU. */
+    private readonly projects;
+    /**
+     * File an emission. Returns the record as stored (with its session call
+     * index), or `null` if the emission was unusable.
+     */
+    record(emission: ExploreEmission): ExploreCallRecord | null;
+    /** Full state for one project, or `null` if it was never queried this session. */
+    forProject(projectRoot: string): ExploreProjectState | null;
+    /** Explore calls made this session against a project (including evicted ones). */
+    callCount(projectRoot: string): number;
+    /** Every project this session has queried, least-recently-used first. */
+    snapshot(): ExploreProjectState[];
+    /**
+     * The bounded view passed INTO a tool call. Trimmed to the most recent
+     * {@link EXPLORE_SESSION_LIMITS.MAX_VIEW_CALLS} calls per project: it crosses a
+     * worker boundary on every explore, so it carries what a dedup/decay decision
+     * needs and not the whole history.
+     */
+    view(): ExploreSessionView;
+    /** Drop everything. Used by tests; a real session just goes away instead. */
+    clear(): void;
+    /**
+     * Fetch a project's state, creating it if new, and mark it most-recently-used.
+     * Evicts the LRU project past the bound — dropping a project entirely (rather
+     * than its detail) is right here: a session that has moved on to four other
+     * repos is not about to re-ask the first one.
+     */
+    private touch;
+    /**
+     * Normalize + bound one call's files: coalesce each file's ranges, then keep
+     * the files that got the most source. A call that renders more files than the
+     * bound has already spread its envelope thin, so the tail files carry the
+     * least — and losing them costs the least.
+     */
+    private boundFiles;
+}
+/**
+ * Read the session view a caller injected into tool args, if any. Defensive:
+ * the key is internal, but the args object comes off the wire, so a client that
+ * spells it itself gets ignored rather than trusted into a crash.
+ */
+export declare function readExploreSessionView(args: Record<string, unknown>): ExploreSessionView | null;
+/**
+ * This session's prior state for one project, from an injected view.
+ *
+ * `null` means NOBODY IS TRACKING (no view was injected — the CLI, a bare
+ * handler). A view that simply hasn't seen this project yet returns an EMPTY
+ * state, not null: the distinction matters to consumers, since "first call of a
+ * tracked session" and "untracked" are different situations.
+ */
+export declare function viewForProject(view: ExploreSessionView | null, projectRoot: string): ExploreProjectState | null;
+//# sourceMappingURL=explore-session-state.d.ts.map

package/dist/mcp/explore-session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore-session-state.d.ts","sourceRoot":"","sources":["../../src/mcp/explore-session-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;IACjC,6EAA6E;;IAE7E,kFAAkF;;IAElF,+DAA+D;;IAE/D,sEAAsE;;IAEtE,4EAA4E;;CAEpE,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACvC,GAAG,GAAE,MAAmD,GACvD;IAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAmBpD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1F;AASD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IAEnE;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,iBAAiB,GAAG,IAAI;IAuB3D,kFAAkF;IAClF,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAK3D,kFAAkF;IAClF,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAItC,yEAAyE;IACzE,QAAQ,IAAI,mBAAmB,EAAE;IAIjC;;;;;OAKG;IACH,IAAI,IAAI,kBAAkB;IAa1B,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAiBb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAgBnB;AAWD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAM/F;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,kBAAkB,GAAG,IAAI,EAC/B,WAAW,EAAE,MAAM,GAClB,mBAAmB,GAAG,IAAI,CAK5B"}

package/dist/mcp/explore-session-state.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Session-scoped `codegraph_explore` call state (CG-17).
+ *
+ * What it holds: for ONE MCP session, per project it queried, what explore has
+ * already returned — the files, the line ranges of source inside them, the bytes
+ * they cost, and where in the session each call fell. Nothing else in the server
+ * knows this today: every explore call is answered as if it were the first one,
+ * which is why a 4th call happily re-serves the same spine it already sent
+ * (#1500) and why the tier's call budget can only be *asked* for rather than
+ * enforced. This module is the record those two behaviours are built on
+ * (CG-18 cross-call dedup, CG-19 budget decay). It changes no response itself.
+ *
+ * Four constraints shape the design, all of them from how the daemon actually
+ * runs:
+ *
+ *   1. **Per session, never persisted.** One instance is owned by an
+ *      {@link ../mcp/session.MCPSession} and dies with the socket. A new agent
+ *      session starts clean — dedup across sessions would suppress source the
+ *      new agent has never seen.
+ *   2. **Per project inside the session.** A session can query several projects
+ *      by `projectPath`, so state is keyed by the RESOLVED project root
+ *      (`cg.getProjectRoot()`), not by whatever path the agent typed.
+ *   3. **Bounded.** A long-lived session must not grow without limit, so
+ *      everything is capped — see {@link EXPLORE_SESSION_LIMITS}. Eviction drops
+ *      DETAIL only: `callCount` and `responseBytes` keep counting past it, since
+ *      decay (CG-19) reads the count and must not be reset by its own bound.
+ *   4. **Daemon-safe.** The daemon shares ONE {@link ../mcp/tools.ToolHandler}
+ *      (and a pool of worker threads) across every connected session, so this
+ *      state can live neither on the handler nor in a worker. It lives on the
+ *      session; the handler is handed it per call, and the record of what a call
+ *      emitted travels back on the {@link ToolResult} so it can be recorded on
+ *      the main thread whether dispatch ran in-process or on a worker.
+ *
+ * Over- vs under-reporting: where a bound forces a choice, this module keeps
+ * FEWER ranges than were emitted, never more. A consumer that under-knows
+ * re-serves something the agent already has (wasteful); one that over-knows
+ * withholds source the agent never saw (a Read — the failure this whole area
+ * exists to prevent).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExploreSessionState = exports.EXPLORE_SESSION_LIMITS = exports.EXPLORE_SESSION_VIEW_ARG = exports.EXPLORE_EMISSION_KEY = void 0;
+exports.exploreProjectKey = exploreProjectKey;
+exports.coalesceRanges = coalesceRanges;
+exports.rangesCover = rangesCover;
+exports.readExploreSessionView = readExploreSessionView;
+exports.viewForProject = viewForProject;
+const path = __importStar(require("path"));
+/**
+ * Property on a {@link ../mcp/tools.ToolResult} carrying what an explore call
+ * emitted. INTERNAL: `ToolHandler.execute` records it and deletes it before the
+ * result reaches the wire, so the agent-facing response is unchanged. It is a
+ * plain-object property (not a Symbol) on purpose — it has to survive the
+ * structured clone back from a query-pool worker.
+ */
+exports.EXPLORE_EMISSION_KEY = '_cgExploreEmission';
+/**
+ * Argument key carrying this session's prior-call view INTO a tool call. Same
+ * reasoning as {@link EXPLORE_EMISSION_KEY}: it crosses the worker boundary, so
+ * it must be a serializable property on the args object.
+ */
+exports.EXPLORE_SESSION_VIEW_ARG = '_cgExploreSession';
+/**
+ * Memory bounds. Every one of them caps DETAIL; none caps the counters that
+ * CG-19's decay reads.
+ *
+ * Sized against how sessions actually behave: an agent explores one project
+ * (occasionally a second in a monorepo) and the tier call budget is 1–5, so the
+ * retained window covers a whole realistic session and the caps only bite on
+ * pathological ones.
+ */
+exports.EXPLORE_SESSION_LIMITS = {
+    /** Distinct projects kept per session; least-recently-used evicted first. */
+    MAX_PROJECTS: 4,
+    /** Call records kept per project (oldest dropped; `callCount` keeps counting). */
+    MAX_CALLS_RETAINED: 8,
+    /** Files kept per call — the ones that got the most source. */
+    MAX_FILES_PER_CALL: 24,
+    /** Line ranges kept per file after coalescing — the largest spans. */
+    MAX_RANGES_PER_FILE: 24,
+    /** Most-recent calls per project included in {@link ExploreSessionView}. */
+    MAX_VIEW_CALLS: 4,
+};
+/**
+ * Key a project root is filed under. Resolved so `/repo` and `/repo/` agree;
+ * case-folded on the two platforms whose filesystems are case-insensitive, so a
+ * drive-letter or capitalization difference doesn't split one project in two.
+ */
+function exploreProjectKey(projectRoot) {
+    const resolved = path.resolve(projectRoot);
+    return process.platform === 'win32' || process.platform === 'darwin'
+        ? resolved.toLowerCase()
+        : resolved;
+}
+/**
+ * Merge overlapping / adjacent spans into the smallest equivalent set, then cap
+ * it. Adjacency (`next.start <= cur.end + 1`) counts as overlap: two ranges that
+ * touch describe one contiguous block of emitted source.
+ *
+ * When the cap bites, the LARGEST spans are kept and the result is re-sorted by
+ * line so the set still reads top-to-bottom — dropping small fragments loses the
+ * least information, and under-reporting is the safe direction (see the module
+ * header).
+ */
+function coalesceRanges(ranges, max = exports.EXPLORE_SESSION_LIMITS.MAX_RANGES_PER_FILE) {
+    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 merged = [];
+    for (const r of valid) {
+        const last = merged[merged.length - 1];
+        if (last && r.start <= last.end + 1)
+            last.end = Math.max(last.end, r.end);
+        else
+            merged.push({ ...r });
+    }
+    if (merged.length <= max)
+        return { ranges: merged, truncated: false };
+    const kept = [...merged]
+        .sort((a, b) => (b.end - b.start) - (a.end - a.start) || a.start - b.start)
+        .slice(0, max)
+        .sort((a, b) => a.start - b.start);
+    return { ranges: kept, truncated: true };
+}
+/** Whether a line falls inside any of the (sorted, coalesced) ranges. */
+function rangesCover(ranges, line) {
+    return ranges.some((r) => line >= r.start && line <= r.end);
+}
+/**
+ * One MCP session's explore history. Created per session, thrown away with it.
+ *
+ * Not thread-shared and not a singleton: two sessions on the same daemon own two
+ * instances and can never observe each other's calls. Every method is total —
+ * malformed input is normalized away rather than thrown, because this sits on
+ * the tool-call path and a bookkeeping bug must never fail an explore.
+ */
+class ExploreSessionState {
+    /** Insertion-ordered; a touched project is re-inserted, so the head is the LRU. */
+    projects = new Map();
+    /**
+     * File an emission. Returns the record as stored (with its session call
+     * index), or `null` if the emission was unusable.
+     */
+    record(emission) {
+        if (!emission || typeof emission.projectRoot !== 'string' || !emission.projectRoot)
+            return null;
+        const key = exploreProjectKey(emission.projectRoot);
+        const state = this.touch(key, emission.projectRoot);
+        state.callCount += 1;
+        state.responseBytes += Math.max(0, emission.responseBytes || 0);
+        const record = {
+            index: state.callCount,
+            projectRoot: emission.projectRoot,
+            query: typeof emission.query === 'string' ? emission.query : '',
+            files: this.boundFiles(emission.files),
+            sourceBytes: Math.max(0, emission.sourceBytes || 0),
+            responseBytes: Math.max(0, emission.responseBytes || 0),
+        };
+        state.calls.push(record);
+        if (state.calls.length > exports.EXPLORE_SESSION_LIMITS.MAX_CALLS_RETAINED) {
+            state.calls.splice(0, state.calls.length - exports.EXPLORE_SESSION_LIMITS.MAX_CALLS_RETAINED);
+        }
+        return record;
+    }
+    /** Full state for one project, or `null` if it was never queried this session. */
+    forProject(projectRoot) {
+        const state = this.projects.get(exploreProjectKey(projectRoot));
+        return state ? cloneProject(state) : null;
+    }
+    /** Explore calls made this session against a project (including evicted ones). */
+    callCount(projectRoot) {
+        return this.projects.get(exploreProjectKey(projectRoot))?.callCount ?? 0;
+    }
+    /** Every project this session has queried, least-recently-used first. */
+    snapshot() {
+        return [...this.projects.values()].map(cloneProject);
+    }
+    /**
+     * The bounded view passed INTO a tool call. Trimmed to the most recent
+     * {@link EXPLORE_SESSION_LIMITS.MAX_VIEW_CALLS} calls per project: it crosses a
+     * worker boundary on every explore, so it carries what a dedup/decay decision
+     * needs and not the whole history.
+     */
+    view() {
+        return {
+            projects: [...this.projects.values()].map((state) => ({
+                projectRoot: state.projectRoot,
+                callCount: state.callCount,
+                responseBytes: state.responseBytes,
+                calls: state.calls
+                    .slice(-exports.EXPLORE_SESSION_LIMITS.MAX_VIEW_CALLS)
+                    .map((c) => ({ ...c, files: c.files.map((f) => ({ ...f, ranges: [...f.ranges] })) })),
+            })),
+        };
+    }
+    /** Drop everything. Used by tests; a real session just goes away instead. */
+    clear() {
+        this.projects.clear();
+    }
+    /**
+     * Fetch a project's state, creating it if new, and mark it most-recently-used.
+     * Evicts the LRU project past the bound — dropping a project entirely (rather
+     * than its detail) is right here: a session that has moved on to four other
+     * repos is not about to re-ask the first one.
+     */
+    touch(key, projectRoot) {
+        const existing = this.projects.get(key);
+        if (existing) {
+            this.projects.delete(key);
+            this.projects.set(key, existing);
+            return existing;
+        }
+        const created = { projectRoot, callCount: 0, responseBytes: 0, calls: [] };
+        this.projects.set(key, created);
+        while (this.projects.size > exports.EXPLORE_SESSION_LIMITS.MAX_PROJECTS) {
+            const lru = this.projects.keys().next().value;
+            if (lru === undefined)
+                break;
+            this.projects.delete(lru);
+        }
+        return created;
+    }
+    /**
+     * Normalize + bound one call's files: coalesce each file's ranges, then keep
+     * the files that got the most source. A call that renders more files than the
+     * bound has already spread its envelope thin, so the tail files carry the
+     * least — and losing them costs the least.
+     */
+    boundFiles(files) {
+        if (!Array.isArray(files) || files.length === 0)
+            return [];
+        const normalized = files
+            .filter((f) => f && typeof f.path === 'string' && f.path.length > 0)
+            .map((f) => {
+            const { ranges, truncated } = coalesceRanges(f.ranges ?? []);
+            const out = { path: f.path, ranges, bytes: Math.max(0, f.bytes || 0) };
+            if (typeof f.fingerprint === 'string' && f.fingerprint)
+                out.fingerprint = f.fingerprint;
+            if (truncated)
+                out.rangesTruncated = true;
+            return out;
+        });
+        if (normalized.length <= exports.EXPLORE_SESSION_LIMITS.MAX_FILES_PER_CALL)
+            return normalized;
+        return [...normalized]
+            .sort((a, b) => b.bytes - a.bytes)
+            .slice(0, exports.EXPLORE_SESSION_LIMITS.MAX_FILES_PER_CALL);
+    }
+}
+exports.ExploreSessionState = ExploreSessionState;
+function cloneProject(state) {
+    return {
+        projectRoot: state.projectRoot,
+        callCount: state.callCount,
+        responseBytes: state.responseBytes,
+        calls: state.calls.map((c) => ({ ...c, files: c.files.map((f) => ({ ...f, ranges: [...f.ranges] })) })),
+    };
+}
+/**
+ * Read the session view a caller injected into tool args, if any. Defensive:
+ * the key is internal, but the args object comes off the wire, so a client that
+ * spells it itself gets ignored rather than trusted into a crash.
+ */
+function readExploreSessionView(args) {
+    const raw = args?.[exports.EXPLORE_SESSION_VIEW_ARG];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const projects = raw.projects;
+    if (!Array.isArray(projects))
+        return null;
+    return { projects: projects.filter((p) => p && typeof p.projectRoot === 'string') };
+}
+/**
+ * This session's prior state for one project, from an injected view.
+ *
+ * `null` means NOBODY IS TRACKING (no view was injected — the CLI, a bare
+ * handler). A view that simply hasn't seen this project yet returns an EMPTY
+ * state, not null: the distinction matters to consumers, since "first call of a
+ * tracked session" and "untracked" are different situations.
+ */
+function viewForProject(view, projectRoot) {
+    if (!view)
+        return null;
+    const key = exploreProjectKey(projectRoot);
+    return view.projects.find((p) => exploreProjectKey(p.projectRoot) === key)
+        ?? { projectRoot, callCount: 0, responseBytes: 0, calls: [] };
+}
+//# sourceMappingURL=explore-session-state.js.map

package/dist/mcp/explore-session-state.js.map

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