@reposkein/mcp 0.2.7 → 0.4.0

package/dist/store/sessionStats.d.ts

@@ -0,0 +1,55 @@
+import { type SessionLogRecord } from "./sessionLog.js";
+/** grep-baseline token-ratio multiplier used for the "estimated context
+ *  tokens saved" stat. Sourced from `mcp/bench/README.md`'s Track 1 retrieval
+ *  benchmark ("Mean token ratio on structural tasks: 8.4x (grep / RepoSkein,
+ *  generous-to-grep)") — a measured, repo-local number, not invented here.
+ *  Always LABEL output built from this as an estimate: it's one repo's
+ *  5-task mean, generalized to every call in a session. */
+export declare const GREP_BASELINE_MULTIPLIER = 8.4;
+export interface SessionSummary {
+    sessionId: string;
+    /** Absolute path to the session's .jsonl file. */
+    file: string;
+    recordCount: number;
+    callsByTool: Record<string, number>;
+    /** Top node ids / file paths touched, most-referenced first. */
+    topTouched: Array<{
+        id: string;
+        count: number;
+    }>;
+    /** Count of ADRs recorded this session (record_decision calls). */
+    decisionsWritten: number;
+    /** Count of semantic summaries written this session (write_semantic_summary calls). */
+    summariesWritten: number;
+    /** ms between the first and last record's `ts`. 0 for a single-record session. */
+    durationMs: number;
+    totalResultBytes: number;
+    /** GREP_BASELINE_MULTIPLIER * totalResultBytes / 4 (≈4 bytes/token), i.e.
+     *  the estimated token cost an equivalent grep-based approach would have
+     *  paid for what RepoSkein returned in `totalResultBytes`. Labeled an
+     *  estimate everywhere it's rendered — see GREP_BASELINE_MULTIPLIER. */
+    estimatedGrepTokens: number;
+    estimatedRepoSkeinTokens: number;
+    estimatedTokensSaved: number;
+    failedCalls: number;
+}
+/** Reads and parses one session's JSONL file. Malformed lines are skipped
+ *  (never thrown) — a session log is best-effort telemetry, not a source of
+ *  truth that must be pristine. */
+export declare function readSessionLog(file: string): SessionLogRecord[];
+/** Every session file for a repo, sorted newest-first (by mtime). */
+export declare function listSessionFiles(repoPath: string): Array<{
+    sessionId: string;
+    file: string;
+    mtimeMs: number;
+}>;
+/** Aggregates one session's records into the report shape rendered by
+ *  `reposkein-mcp stats`. Pure function over already-parsed records so it's
+ *  cheap to unit test independent of the filesystem. */
+export declare function summarizeSession(sessionId: string, file: string, records: SessionLogRecord[]): SessionSummary;
+/** Merges several sessions' records into one combined summary (`--all`) —
+ *  same aggregation, over the union of records, with a synthetic id. */
+export declare function summarizeSessions(sessions: Array<{
+    sessionId: string;
+    file: string;
+}>): SessionSummary;

package/dist/store/sessionStats.js

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sessionsDir } from "./sessionLog.js";
+/** grep-baseline token-ratio multiplier used for the "estimated context
+ *  tokens saved" stat. Sourced from `mcp/bench/README.md`'s Track 1 retrieval
+ *  benchmark ("Mean token ratio on structural tasks: 8.4x (grep / RepoSkein,
+ *  generous-to-grep)") — a measured, repo-local number, not invented here.
+ *  Always LABEL output built from this as an estimate: it's one repo's
+ *  5-task mean, generalized to every call in a session. */
+export const GREP_BASELINE_MULTIPLIER = 8.4;
+/** Reads and parses one session's JSONL file. Malformed lines are skipped
+ *  (never thrown) — a session log is best-effort telemetry, not a source of
+ *  truth that must be pristine. */
+export function readSessionLog(file) {
+    if (!existsSync(file))
+        return [];
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (typeof rec.tool === "string" && typeof rec.ts === "string") {
+                out.push({
+                    ts: rec.ts,
+                    tool: rec.tool,
+                    argsShape: Array.isArray(rec.argsShape) ? rec.argsShape : [],
+                    resultBytes: typeof rec.resultBytes === "number" ? rec.resultBytes : 0,
+                    ...(Array.isArray(rec.nodeIds) && rec.nodeIds.length ? { nodeIds: rec.nodeIds } : {}),
+                    ok: rec.ok !== false,
+                });
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return out;
+}
+/** Every session file for a repo, sorted newest-first (by mtime). */
+export function listSessionFiles(repoPath) {
+    const dir = sessionsDir(repoPath);
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((name) => {
+        const file = join(dir, name);
+        let mtimeMs = 0;
+        try {
+            mtimeMs = statSync(file).mtimeMs;
+        }
+        catch {
+            /* keep 0 — still listed, just sorts last */
+        }
+        return { sessionId: name.replace(/\.jsonl$/, ""), file, mtimeMs };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/** Tools whose calls count as "summaries/ADRs written this session". */
+const DECISION_TOOLS = new Set(["record_decision"]);
+const SUMMARY_TOOLS = new Set(["write_semantic_summary"]);
+/** Aggregates one session's records into the report shape rendered by
+ *  `reposkein-mcp stats`. Pure function over already-parsed records so it's
+ *  cheap to unit test independent of the filesystem. */
+export function summarizeSession(sessionId, file, records) {
+    const callsByTool = {};
+    const touchedCounts = new Map();
+    let decisionsWritten = 0;
+    let summariesWritten = 0;
+    let totalResultBytes = 0;
+    let failedCalls = 0;
+    let minTs = Infinity;
+    let maxTs = -Infinity;
+    for (const rec of records) {
+        callsByTool[rec.tool] = (callsByTool[rec.tool] ?? 0) + 1;
+        totalResultBytes += rec.resultBytes;
+        if (!rec.ok)
+            failedCalls++;
+        if (DECISION_TOOLS.has(rec.tool))
+            decisionsWritten++;
+        if (SUMMARY_TOOLS.has(rec.tool))
+            summariesWritten++;
+        for (const id of rec.nodeIds ?? [])
+            touchedCounts.set(id, (touchedCounts.get(id) ?? 0) + 1);
+        const t = Date.parse(rec.ts);
+        if (!Number.isNaN(t)) {
+            if (t < minTs)
+                minTs = t;
+            if (t > maxTs)
+                maxTs = t;
+        }
+    }
+    const topTouched = [...touchedCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 10)
+        .map(([id, count]) => ({ id, count }));
+    const durationMs = Number.isFinite(minTs) && Number.isFinite(maxTs) && maxTs > minTs ? maxTs - minTs : 0;
+    // ~4 bytes/token is the common rough estimator (also used by mcp/bench —
+    // see its token cost model) — deliberately simple and labeled an estimate.
+    const estimatedRepoSkeinTokens = Math.round(totalResultBytes / 4);
+    const estimatedGrepTokens = Math.round(estimatedRepoSkeinTokens * GREP_BASELINE_MULTIPLIER);
+    const estimatedTokensSaved = estimatedGrepTokens - estimatedRepoSkeinTokens;
+    return {
+        sessionId,
+        file,
+        recordCount: records.length,
+        callsByTool,
+        topTouched,
+        decisionsWritten,
+        summariesWritten,
+        durationMs,
+        totalResultBytes,
+        estimatedGrepTokens,
+        estimatedRepoSkeinTokens,
+        estimatedTokensSaved,
+        failedCalls,
+    };
+}
+/** Merges several sessions' records into one combined summary (`--all`) —
+ *  same aggregation, over the union of records, with a synthetic id. */
+export function summarizeSessions(sessions) {
+    const allRecords = sessions.flatMap((s) => readSessionLog(s.file));
+    const label = sessions.length === 1 ? sessions[0].sessionId : `${sessions.length} sessions`;
+    return summarizeSession(label, sessions.map((s) => s.file).join(","), allRecords);
+}
+//# sourceMappingURL=sessionStats.js.map

package/dist/store/sessionStats.js.map

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

package/dist/store/sidecar.d.ts

@@ -1,4 +1,5 @@
-/** A persisted summary record (git-ignored .reposkein/local/summaries.jsonl). */
+import { type SummaryAccumulator } from "./summaryShards.js";
+/** A persisted summary record (git-ignored .reposkein/local/summaries-<agent>.jsonl). */
 export interface SidecarSummary {
     id: string;
     semantic_summary: string;
@@ -7,10 +8,45 @@ export interface SidecarSummary {
     summary_at: string;
     summary_by: string;
 }
-export declare function sidecarPath(repoPath: string): string;
+/** Directory holding every agent's sidecar. Git-ignored in full. */
+export declare function sidecarDir(repoPath: string): string;
+/** Filesystem-safe slug for the writing agent.
+ *
+ *  Untrusted input: REPOSKEIN_AGENT comes from whatever launched the server, so
+ *  it is reduced to `[a-z0-9._-]` and capped. A value that reduces to nothing
+ *  (or is absent) falls back to "agent", which is also the pre-multi-agent
+ *  name — so a single-agent setup keeps one stable file. */
+export declare function agentSlug(agent?: string | undefined): string;
+/** THIS process's sidecar: one file per agent.
+ *
+ *  A single shared `local/summaries.jsonl` meant two agents running against the
+ *  same checkout silently overwrote each other — `upsertSidecar` rewrites the
+ *  whole file, so the slower writer's prose vanished with no error anywhere.
+ *  One file per writer removes the shared mutable state; the indexer folds
+ *  every `local/summaries*.jsonl` into the committed shards. */
+export declare function sidecarPath(repoPath: string, agent?: string): string;
+/** Every agent's sidecar in this repo, sorted, so reads are deterministic and
+ *  independent of directory order. Includes the pre-split
+ *  `local/summaries.jsonl` an older client may still be writing. */
+export declare function sidecarPaths(repoPath: string): string[];
 /** Reads the sidecar into a map keyed by node id. Missing file → empty map.
  *  Best-effort: malformed lines / read errors are skipped. */
 export declare function readSidecar(path: string): Map<string, SidecarSummary>;
+/** Every agent's sidecar records, folded through the SAME rules the Rust
+ *  indexer applies — `beats` within the sidecar set, losers preserved — so the
+ *  server serves exactly the record the next `index` is going to write.
+ *
+ *  This used to be a plain last-file-wins merge, which disagreed with the
+ *  indexer whenever two agents summarised the same node, and dropped the loser
+ *  with no trace. Callers should hand `conflicts` to `recordSummaryConflicts`. */
+export declare function loadAllSidecars(repoPath: string): SummaryAccumulator;
+/** Convenience view of `loadAllSidecars` for callers that only want the
+ *  winning record per node id. Divergence losers are dropped on the floor
+ *  here, so prefer `loadAllSidecars` anywhere they can be recorded. */
+export declare function readAllSidecars(repoPath: string): Map<string, SidecarSummary>;
 /** Upserts one record and rewrites the sidecar sorted by id (deterministic, no
- *  duplicate lines). Creates the local/ dir if needed. Best-effort. */
+ *  duplicate lines). Creates the local/ dir if needed. Best-effort.
+ *
+ *  Rewriting the whole file is safe only because `path` belongs to one agent:
+ *  see `sidecarPath`. */
 export declare function upsertSidecar(path: string, rec: SidecarSummary): void;

package/dist/store/sidecar.js

@@ -1,7 +1,49 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-export function sidecarPath(repoPath) {
-    return join(repoPath, ".reposkein", "local", "summaries.jsonl");
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { absorbSummaryLines, emptyAccumulator, } from "./summaryShards.js";
+/** Directory holding every agent's sidecar. Git-ignored in full. */
+export function sidecarDir(repoPath) {
+    return join(repoPath, ".reposkein", "local");
+}
+/** Filesystem-safe slug for the writing agent.
+ *
+ *  Untrusted input: REPOSKEIN_AGENT comes from whatever launched the server, so
+ *  it is reduced to `[a-z0-9._-]` and capped. A value that reduces to nothing
+ *  (or is absent) falls back to "agent", which is also the pre-multi-agent
+ *  name — so a single-agent setup keeps one stable file. */
+export function agentSlug(agent = process.env.REPOSKEIN_AGENT) {
+    const slug = (agent ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "")
+        .slice(0, 40)
+        .replace(/[-.]+$/, "");
+    return slug === "" ? "agent" : slug;
+}
+/** THIS process's sidecar: one file per agent.
+ *
+ *  A single shared `local/summaries.jsonl` meant two agents running against the
+ *  same checkout silently overwrote each other — `upsertSidecar` rewrites the
+ *  whole file, so the slower writer's prose vanished with no error anywhere.
+ *  One file per writer removes the shared mutable state; the indexer folds
+ *  every `local/summaries*.jsonl` into the committed shards. */
+export function sidecarPath(repoPath, agent) {
+    return join(sidecarDir(repoPath), `summaries-${agentSlug(agent)}.jsonl`);
+}
+/** Every agent's sidecar in this repo, sorted, so reads are deterministic and
+ *  independent of directory order. Includes the pre-split
+ *  `local/summaries.jsonl` an older client may still be writing. */
+export function sidecarPaths(repoPath) {
+    const dir = sidecarDir(repoPath);
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.startsWith("summaries") && f.endsWith(".jsonl"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
 }
 /** Reads the sidecar into a map keyed by node id. Missing file → empty map.
  *  Best-effort: malformed lines / read errors are skipped. */
@@ -38,8 +80,50 @@ export function readSidecar(path) {
     }
     return map;
 }
+/** Every agent's sidecar records, folded through the SAME rules the Rust
+ *  indexer applies — `beats` within the sidecar set, losers preserved — so the
+ *  server serves exactly the record the next `index` is going to write.
+ *
+ *  This used to be a plain last-file-wins merge, which disagreed with the
+ *  indexer whenever two agents summarised the same node, and dropped the loser
+ *  with no trace. Callers should hand `conflicts` to `recordSummaryConflicts`. */
+export function loadAllSidecars(repoPath) {
+    const acc = emptyAccumulator();
+    for (const p of sidecarPaths(repoPath)) {
+        let text;
+        try {
+            text = readFileSync(p, "utf8");
+        }
+        catch {
+            continue;
+        }
+        absorbSummaryLines(acc, `local/${basename(p)}`, text);
+    }
+    return acc;
+}
+/** Convenience view of `loadAllSidecars` for callers that only want the
+ *  winning record per node id. Divergence losers are dropped on the floor
+ *  here, so prefer `loadAllSidecars` anywhere they can be recorded. */
+export function readAllSidecars(repoPath) {
+    const merged = new Map();
+    for (const [id, rec] of loadAllSidecars(repoPath).summaries) {
+        const s = (k) => typeof rec.props[k] === "string" ? rec.props[k] : "";
+        merged.set(id, {
+            id,
+            semantic_summary: s("semantic_summary"),
+            summary_of_hash: s("summary_of_hash"),
+            summary_model: s("summary_model"),
+            summary_at: s("summary_at"),
+            summary_by: s("summary_by"),
+        });
+    }
+    return merged;
+}
 /** Upserts one record and rewrites the sidecar sorted by id (deterministic, no
- *  duplicate lines). Creates the local/ dir if needed. Best-effort. */
+ *  duplicate lines). Creates the local/ dir if needed. Best-effort.
+ *
+ *  Rewriting the whole file is safe only because `path` belongs to one agent:
+ *  see `sidecarPath`. */
 export function upsertSidecar(path, rec) {
     const map = readSidecar(path);
     map.set(rec.id, rec);

package/dist/store/sidecar.js.map

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

package/dist/store/summaryShards.d.ts

@@ -0,0 +1,117 @@
+/** Reader for the committed authored summaries, `.reposkein/summaries/<xx>.jsonl`.
+ *
+ *  Sharding replaced a single `.reposkein/summaries.jsonl` for the reason
+ *  `docs/migrations/2026-08-06-stop-committing-derived-graph.md` records: one
+ *  committed file that every branch rewrites conflicts on every merge, and no
+ *  `.gitattributes` rule can fix it, because a forge computes mergeability in a
+ *  bare repo where tree-level attributes are never consulted. File granularity
+ *  is the only thing that works there — the same reason decisions are one file
+ *  each.
+ *
+ *  This module ONLY READS. The Rust indexer is the sole writer of committed
+ *  shards, so byte-identical output has exactly one serializer to hold to it
+ *  (serde_json and JSON.stringify differ on escapes and number formatting).
+ *  Writes from this process go to the git-ignored per-agent sidecar, which the
+ *  next `index` folds into the shards.
+ *
+ *  Reading never needs a shard key — `readdir` enumerates the files — which is
+ *  why no BLAKE3 implementation is required on this side.
+ *
+ *  Tolerance is the other half. A shard is a MERGED file: it can carry git
+ *  conflict markers, duplicate lines from a `merge=union` resolution, or two
+ *  genuinely different summaries for the same node. None of that may take
+ *  recall down, and none of it may silently destroy authored prose — the same
+ *  contract `loadDecisions` keeps for a damaged decision file. */
+export interface SummaryShardRecord {
+    id: string;
+    /** Every field except `id`, exactly as parsed. */
+    props: Record<string, unknown>;
+    /** The raw source line, which is also the divergence tiebreak. */
+    line: string;
+}
+export interface LoadedSummaryShards {
+    /** Winner per node id, insertion-ordered by id. */
+    summaries: Map<string, SummaryShardRecord>;
+    /** Divergence losers, preserved rather than dropped. */
+    conflicts: SummaryShardRecord[];
+    warnings: string[];
+    /** Set when the pre-sharding `.reposkein/summaries.jsonl` is still present —
+     *  doctor turns this into "run `reposkein-indexer index` to migrate". */
+    legacyFilePresent: boolean;
+}
+export declare function summariesDir(repoPath: string): string;
+/** The pre-sharding committed file. Still read (dual-read) for one release. */
+export declare function legacySummariesPath(repoPath: string): string;
+export declare function conflictsPath(repoPath: string): string;
+/** Mirrors the Rust `is_shard_file_name`: exactly two lowercase hex chars. */
+export declare function isShardFileName(name: string): boolean;
+/** A line git left behind from an unresolved textual merge. A canonical
+ *  summary line always starts with `{`, so a marker run is damage, not data. */
+export declare function isConflictMarker(line: string): boolean;
+/** Whether these props carry an authored summary worth keeping.
+ *
+ *  Deliberately identical to the Rust `has_summary`. The two languages read the
+ *  same committed shards, so a record one accepts and the other rejects is a
+ *  divergence between what the server serves and what the indexer writes — and
+ *  a record with nothing in it must never displace one that has prose, in
+ *  either language. Pinned by the `null-valued`/`non-string` fixture vectors. */
+export declare function hasSummary(props: Record<string, unknown>): boolean;
+/** Deterministic winner between two records claiming the same node id, when
+ *  nothing is known about where either came from:
+ *  newer `summary_at`, then smaller raw line by UTF-8 byte order. Both are
+ *  pure functions of bytes on disk, so every machine — and the Rust indexer —
+ *  picks the same winner without coordinating. Kept in lockstep with the Rust
+ *  `beats` by the shared vectors in `fixtures/summary-shard-vectors.json`.
+ *
+ *  This is the rule for records found in the SAME source (two lines of one
+ *  merged shard, two agents' sidecars). Across sources of known provenance,
+ *  use `supersedes`. */
+export declare function beats(candidate: SummaryShardRecord, incumbent: SummaryShardRecord): boolean;
+/** Whether a record from a strictly NEWER-provenance source displaces one
+ *  already held from an older source.
+ *
+ *  `summary_at` is day-precision (PRD §6.2.5 keeps wall-clock time out of
+ *  committed bytes), so re-summarising a node already summarised today TIES.
+ *  Resolving that tie by byte order would silently discard the rewrite. A
+ *  newer source therefore wins unless it is *strictly older* — which is the
+ *  case that matters, because that is a stale local record about to clobber a
+ *  teammate's newer one. Mirrors the Rust `supersedes`. */
+export declare function supersedes(candidate: SummaryShardRecord, incumbent: SummaryShardRecord): boolean;
+export interface SummaryAccumulator {
+    summaries: Map<string, SummaryShardRecord>;
+    conflicts: SummaryShardRecord[];
+    warnings: string[];
+}
+export declare function emptyAccumulator(): SummaryAccumulator;
+/** Folds a whole source of strictly NEWER provenance into `acc`. Mirrors the
+ *  Rust `absorb_source`: displacement uses `supersedes`, and every displaced
+ *  record is preserved. */
+export declare function absorbSummarySource(acc: SummaryAccumulator, other: SummaryAccumulator): void;
+/** Folds one file's text in, resolving same-source records with `beats`.
+ *  Exported for the shared vectors. */
+export declare function absorbSummaryLines(acc: SummaryAccumulator, source: string, text: string): void;
+/** Reads every committed shard plus the pre-sharding file, tolerantly.
+ *  A missing directory is the normal state for a repo with no authored prose,
+ *  and returns an empty result rather than an error. */
+export declare function loadSummaryShards(repoPath: string): LoadedSummaryShards;
+/** A cheap fingerprint of everything the summary overlay reads on disk.
+ *
+ *  The store keys its reload on this, so a `git pull` that brings in a
+ *  teammate's shards — or another agent's sidecar write on this machine — is
+ *  visible without restarting the process. Stat calls only, O(shards +
+ *  sidecars), no content read, because this runs on every read and not just on
+ *  change. mtime alone is not enough on filesystems with coarse timestamps, so
+ *  size rides along.
+ *
+ *  `sidecarFiles` is injected rather than imported to keep this module free of
+ *  a cycle with sidecar.ts, which imports the fold from here. */
+export declare function summaryShardsStamp(repoPath: string, sidecarFiles?: (repoPath: string) => string[]): string;
+/** Merges divergence losers into the git-ignored `local/conflicts.jsonl`.
+ *
+ *  Deduped and sorted, so repeated reads converge instead of growing the file,
+ *  and never truncating: a loser recorded by an earlier run (or by the indexer)
+ *  stays. Best-effort — failing to record a conflict must not break a tool
+ *  call. Mirrors the Rust `conflicts_to_jsonl`. */
+export declare function recordSummaryConflicts(repoPath: string, losers: readonly SummaryShardRecord[]): void;
+/** How many divergence losers are on record. Doctor surfaces this. */
+export declare function countRecordedConflicts(repoPath: string): number;