heyspex 0.1.0

package/vendor/heyspex-mcp/peer-presence.mjs

@@ -0,0 +1,430 @@
+/**
+ * Peer presence — every tool response tells the calling agent which OTHER agent
+ * sessions are live and what they hold ([[HS-89JR-ARLV-EPIC-peer-presence-on-every-heyspex-call]],
+ * owner directive 2026-08-14; capture [[HS-3XIE-GVNH-CAP-parallel-agents-are-still-stepping-on-ea]] —
+ * six cross-session collisions in one day because coordination data existed but
+ * was never pushed to the agents).
+ *
+ * Claim SSOT is the console (`GET /api/claims`) — NOT `.heyspex/active-claims.json`,
+ * which is stale on disk (HS-AG04). The fetch is fail-open with a short timeout,
+ * a positive cache (a burst of tool calls does not multiply requests) and a
+ * negative cache (a down console must not add timeout latency to every call).
+ * Presence INFORMS; leases enforce (HS-O4J0) — nothing here ever blocks a write.
+ *
+ * Pure core + thin shell (unit-test-authoring-protocol): buildPeerAgentsBlock is
+ * pure and fully tested against fixtures; fetchPeerAgents/appendPeerPresence are
+ * the fail-open shells the cli.mjs dispatch calls.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PEER_AGENTS_DEFAULT_LIMIT = 8;
+export const PEER_DIRS_CAP = 4;
+// [[HS-QQJP]] — "someone is working under spex-console/src" is nearly every file
+// in this repo, so the round-2 two-segment cap does not answer "will my next
+// write collide". Depth is the one direction of the four in the task that was
+// not already shipped: stage (row.stage) and recency (row.last_active) already
+// exist per session, and "count shape" already exists as files_touched. Depth
+// alone was the gap, verified against .heyspex/wip-state.json's real shape
+// (2026-08-15): most files cluster several segments deep under one project
+// (e.g. companion/src/HeySpex.Companion.Core/Gather/*.cs), so a fixed two-segment
+// cap throws away exactly the information a peer needs. Deepen ONLY when at
+// least two files agree past the two-segment root — a lone file going deeper
+// would just be a disguised file path, which the contract forbids.
+export const PEER_DIR_HINT_MAX_DEPTH = 4;
+// [[HS-O8YN]] — 1200ms lost the race against a real dev-server /api/claims read
+// in 4 of 8 live-measured samples (2026-08-15): 2325, 2767, 1559, 845, 901,
+// 1341, 920, 889 ms — 4/8 over 1200ms, worst case 2767ms. 3000ms covers every
+// sample above with headroom. Do not lower this without a fresh measurement.
+const DEFAULT_TIMEOUT_MS = 3000;
+export const PEER_PRESENCE_DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+const CACHE_TTL_MS = 5_000;
+const NEGATIVE_CACHE_MS = 30_000;
+
+// [[HS-ZYPM]] — the 1500-char budget was stated in round 2 and certified at 1442
+// against a synthetic fixture, but nothing in code ever checked it. Measured
+// against the REAL .heyspex/wip-state.json ledger the same block lands at 1500 at
+// six peers and 1965 at eight — and it lands on EVERY tool response, which is the
+// whole reason the budget exists. A stated limit nothing checks is not a limit,
+// so the render path now trims to fit and reports what it dropped.
+export const PEER_BLOCK_CHAR_BUDGET = 1500;
+const PEER_BLOCK_PREFIX = 'PEER AGENTS — other live sessions; avoid claiming their specs or editing their scope: ';
+
+/**
+ * Directory segments for one WIP path (filename dropped), normalized to
+ * forward slashes. Returns null for non-strings/empty paths; [] for a
+ * root-level file (no directory to report — keeping its bare name would put
+ * a full file path in the block, which the scope-hint contract forbids,
+ * HS-NKMN AC2). Callers that only want the round-2 two-segment cap use
+ * `baseDirKey`; buildPeerAgentsBlock uses the full segment list to check
+ * whether a group of files agrees on a deeper common root (HS-QQJP).
+ */
+function dirSegments(path) {
+  if (typeof path !== 'string') return null;
+  const segments = path.replace(/\\/g, '/').split('/').filter(Boolean);
+  if (segments.length === 0) return null;
+  return segments.slice(0, -1);
+}
+
+/** The round-2 grouping key: "." for root-level files, else the first two directory segments. */
+function baseDirKey(segments) {
+  return segments.length === 0 ? '.' : segments.slice(0, 2).join('/');
+}
+
+/**
+ * Given every file that reduced to the same `baseDirKey`, decide whether they
+ * agree on a directory deeper than the two-segment default and, if so, report
+ * that deeper shared root instead — up to PEER_DIR_HINT_MAX_DEPTH segments.
+ * Requires at least two files: a lone file going deeper would just be a
+ * disguised file path (HS-NKMN's "never a full path" contract), and it isn't
+ * "agreement" if there is only one data point.
+ */
+function deepestCommonHint(key, segsList) {
+  if (key === '.' || segsList.length < 2) return key;
+  const baseDepth = key.split('/').length;
+  const minLen = Math.min(...segsList.map((s) => s.length));
+  const cap = Math.min(PEER_DIR_HINT_MAX_DEPTH, minLen);
+  let depth = baseDepth;
+  while (depth < cap && segsList.every((s) => s[depth] === segsList[0][depth])) depth++;
+  return segsList[0].slice(0, depth).join('/');
+}
+
+/**
+ * Pure core: turn the console's claims list (+ optional wip-state) into a compact
+ * peer_agents block, or null when no OTHER live session exists.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.claims        rows from GET /api/claims (specId, agent, sessionId, effectiveStatus, staleAt, expiresAt, lastActivityAt, currentStage, …)
+ * @param {object} [opts.wip]         parsed .heyspex/wip-state.json ({ [specId]: { sessionId, filesTouched: [...] } })
+ * @param {number} [opts.nowMs]       clock injection for staleness tests
+ * @param {string} [opts.selfSessionId] the CALLER's session — always excluded
+ * @param {number} [opts.limit]       max rows before truncation (more_count carries the rest)
+ * @returns {{peer_agents: Array, more_count?: number} | null}
+ */
+export function buildPeerAgentsBlock({ claims, wip = null, nowMs = Date.now(), selfSessionId = null, limit = PEER_AGENTS_DEFAULT_LIMIT }) {
+  if (!Array.isArray(claims) || claims.length === 0) return null;
+  const bySession = new Map();
+  for (const c of claims) {
+    if (!c || typeof c !== 'object') continue;
+    const sid = c.sessionId ?? null;
+    if (!sid || sid === selfSessionId) continue;
+    const staleAtMs = c.staleAt ? Date.parse(c.staleAt) : null;
+    const expiresAtMs = c.expiresAt ? Date.parse(c.expiresAt) : null;
+    if ((staleAtMs != null && staleAtMs < nowMs) || (expiresAtMs != null && expiresAtMs < nowMs)) continue;
+    if (c.effectiveStatus != null && c.effectiveStatus !== 'working') continue;
+    const row = bySession.get(sid) ?? {
+      _sid: sid,
+      _activityMs: 0,
+      agent: c.agent ?? 'unknown',
+      session: String(sid).slice(0, 8),
+      spec_ids: [],
+      stage: null,
+      last_active: null,
+    };
+    if (c.specId && !row.spec_ids.includes(c.specId)) row.spec_ids.push(c.specId);
+    if (c.currentStage) row.stage = c.currentStage;
+    const activityMs = c.lastActivityAt ? Date.parse(c.lastActivityAt) : null;
+    if (activityMs != null && activityMs > row._activityMs) {
+      row._activityMs = activityMs;
+      row.last_active = c.lastActivityAt;
+    }
+    bySession.set(sid, row);
+  }
+  if (bySession.size === 0) return null;
+
+  // Scope hints from the WIP ledger: how many files that session's work touches
+  // (the COUNT only, never the list — mcp-tool-response-size-budget) plus WHICH
+  // directories, as de-duped two-segment hints capped at PEER_DIRS_CAP (first
+  // seen, round-2 order preserved) with a dirs_more overflow count. Only the
+  // FIRST shown bucket is widened to the deepest root ALL of its files agree
+  // on, up to PEER_DIR_HINT_MAX_DEPTH ([[HS-QQJP]]) — deepening every shown
+  // bucket, plus maxing every other field at once (long agent names, the
+  // longest stage verb, 4-digit files_touched), measured 2231-2583 chars on
+  // an 8-row block, well over the 1500 budget; depth on one root per row
+  // against round 2's own already-certified 1442-char fixture measures 1479
+  // (see peer-presence.test.mjs "measured" case) — 21 chars of headroom, so
+  // this is deliberately spent on the single most collision-relevant root per
+  // row, not spread across all four. Advisory visibility only — derived from
+  // this same wip read (zero new round trips), never a file list, never a
+  // claim or lock ([[HS-45FR-A9SI-RES-parallel-agent-collision-enforcement]]
+  // §"Design constraint — derive scope, don't claim it").
+  if (wip && typeof wip === 'object') {
+    for (const row of bySession.values()) {
+      let filesTouched = 0;
+      const buckets = new Map(); // baseDirKey -> segments[] for every file in that bucket, in first-seen order
+      for (const [specId, entry] of Object.entries(wip)) {
+        if (!entry || typeof entry !== 'object') continue;
+        const matches = entry.sessionId === row._sid || row.spec_ids.includes(specId);
+        if (!matches || !Array.isArray(entry.filesTouched)) continue;
+        filesTouched = Math.max(filesTouched, entry.filesTouched.length);
+        for (const file of entry.filesTouched) {
+          const segs = dirSegments(file);
+          if (segs == null) continue;
+          const key = baseDirKey(segs);
+          let bucket = buckets.get(key);
+          if (!bucket) buckets.set(key, (bucket = []));
+          bucket.push(segs);
+        }
+      }
+      if (filesTouched > 0) row.files_touched = filesTouched;
+      if (buckets.size > 0) {
+        const dirs = [];
+        let i = 0;
+        for (const [key, segsList] of buckets) {
+          if (i >= PEER_DIRS_CAP) break;
+          dirs.push(i === 0 ? deepestCommonHint(key, segsList) : key);
+          i++;
+        }
+        row.dirs = dirs;
+        const overflow = buckets.size - dirs.length;
+        if (overflow > 0) row.dirs_more = overflow;
+      }
+    }
+  }
+
+  const rows = [...bySession.values()]
+    .sort((a, b) => b._activityMs - a._activityMs)
+    .map(({ _sid, _activityMs, ...publicRow }) => publicRow);
+  const capped = rows.slice(0, limit);
+  const moreCount = rows.length - capped.length;
+  return { peer_agents: capped, ...(moreCount > 0 ? { more_count: moreCount } : {}) };
+}
+
+/** Best-effort local read of the WIP ledger — null on any problem, never throws. */
+export function readWipState(vaultRoot) {
+  try {
+    if (!vaultRoot) return null;
+    const parsed = JSON.parse(readFileSync(join(vaultRoot, '.heyspex', 'wip-state.json'), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Positive + negative caches — module-level on purpose (one MCP server process
+// serves one session; a burst of tool calls shares one claims snapshot).
+let claimsCache = { atMs: 0, url: null, claims: null };
+let failedUntilMs = 0;
+// [[HS-O8YN]] direction 3: last successfully built block + when, so a failed
+// fetch can serve slightly-stale data instead of nothing (the negative cache is
+// already 30s, so a stale block is strictly better than silence). Null block
+// still counts as "known" — it means the last real check found no peers.
+let lastGoodBlock = null;
+let lastGoodAtMs = 0;
+let lastGoodChecked = false;
+
+/** Test hook: clear all caches between cases. */
+export function resetPeerPresenceCache() {
+  claimsCache = { atMs: 0, url: null, claims: null };
+  failedUntilMs = 0;
+  lastGoodBlock = null;
+  lastGoodAtMs = 0;
+  lastGoodChecked = false;
+}
+
+async function readClaimsFromConsole(consoleUrl, fetchFn, timeoutMs, headers) {
+  const url = `${String(consoleUrl).replace(/\/+$/, '')}/api/claims`;
+  const init = { signal: AbortSignal.timeout?.(timeoutMs) };
+  // Cloud console gates /api/claims behind the same bearer every other console
+  // call sends (guardMcpAuth) — an unauthenticated probe 401s on EVERY tool
+  // call there, rendering the "PEER AGENTS UNAVAILABLE" line while the calls
+  // themselves succeed (HS-0C12-3UIK sibling finding). No headers → exactly
+  // the old request, so the local dev console path is byte-identical.
+  if (headers && Object.keys(headers).length > 0) init.headers = headers;
+  const res = await fetchFn(url, init);
+  if (!res?.ok) return null;
+  const body = await res.json();
+  return Array.isArray(body?.claims) ? body.claims : null;
+}
+
+/** Build the failure-path result: stale-but-known data beats nothing (direction 3). */
+function staleResult(nowMs) {
+  if (lastGoodChecked) {
+    return { block: lastGoodBlock, ok: false, stale: true, ageMs: nowMs - lastGoodAtMs };
+  }
+  return { block: null, ok: false, stale: false, ageMs: null };
+}
+
+/**
+ * Internal shell: fetch live claims (cached) and build the block, reporting HOW
+ * the result was obtained — `ok: true` for a fresh/cached-fresh read, `ok: false`
+ * for a failed/timed-out read (optionally with a stale `block` served from the
+ * last known-good check). This is the piece that lets a caller tell "checked,
+ * no peers" apart from "could not check" ([[HS-O8YN]]) — fetchPeerAgents below
+ * collapses both failure shapes back to null for callers that only want the block.
+ * Fail-open — any error, non-OK response, or unreachable console never throws.
+ */
+async function resolvePeerPresence({
+  consoleUrl,
+  selfSessionId = null,
+  vaultRoot = null,
+  fetchFn = fetch,
+  nowMs = Date.now(),
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  limit = PEER_AGENTS_DEFAULT_LIMIT,
+  cacheTtlMs = CACHE_TTL_MS,
+  negativeCacheMs = NEGATIVE_CACHE_MS,
+  /** Outbound auth header(s) for the console read (cloud bearer). Optional. */
+  headers = null,
+} = {}) {
+  try {
+    if (!consoleUrl) return { block: null, ok: false, stale: false, ageMs: null };
+    let claims = null;
+    if (claimsCache.claims && claimsCache.url === consoleUrl && nowMs - claimsCache.atMs < cacheTtlMs) {
+      claims = claimsCache.claims;
+    } else if (nowMs < failedUntilMs) {
+      return staleResult(nowMs);
+    } else {
+      claims = await readClaimsFromConsole(consoleUrl, fetchFn, timeoutMs, headers);
+      if (claims == null) {
+        failedUntilMs = nowMs + negativeCacheMs;
+        return staleResult(nowMs);
+      }
+      claimsCache = { atMs: nowMs, url: consoleUrl, claims };
+      failedUntilMs = 0;
+    }
+    const block = buildPeerAgentsBlock({ claims, wip: readWipState(vaultRoot), nowMs, selfSessionId, limit });
+    lastGoodBlock = block;
+    lastGoodAtMs = nowMs;
+    lastGoodChecked = true;
+    return { block, ok: true, stale: false, ageMs: null };
+  } catch {
+    failedUntilMs = nowMs + negativeCacheMs;
+    return staleResult(nowMs);
+  }
+}
+
+/**
+ * Thin shell: fetch live claims (cached) and build the block. Fail-open — any
+ * error, non-OK response, or unreachable console returns null and arms the
+ * negative cache so subsequent tool calls skip the attempt entirely. Kept as a
+ * plain block-or-null contract for callers that don't need failure visibility;
+ * appendPeerPresence uses resolvePeerPresence directly instead.
+ */
+export async function fetchPeerAgents(opts = {}) {
+  const { block } = await resolvePeerPresence(opts);
+  return block;
+}
+
+/**
+ * Trim a block until the line it renders to fits PEER_BLOCK_CHAR_BUDGET ([[HS-ZYPM]]).
+ * Pure — the caller's block is never mutated.
+ *
+ * What goes first is what costs most and is worth least. The directory hints are
+ * the entire overage: the same 8-row block measures 1965 chars with hints and
+ * 1141 without, so hints are shed before anything else, and always from whichever
+ * row is currently carrying the most. That way every row keeps its FIRST hint —
+ * the deepest, most collision-relevant one — for as long as possible, which is
+ * the only hint a peer usually acts on.
+ *
+ * Nothing is dropped quietly. A shed hint is added to that row's `dirs_more`, a
+ * dropped row is added to `more_count`, and `budget_trimmed: true` marks that the
+ * trim came from the budget rather than from PEER_AGENTS_DEFAULT_LIMIT.
+ *
+ * The last row is never dropped, even if it alone exceeds the budget. Rendering
+ * an empty peer list to save characters would tell a live agent it is alone when
+ * it is not, which is the exact failure [[HS-O8YN]] exists to prevent.
+ */
+export function fitPeerAgentsBlock(block, opts = {}) {
+  const budget = opts.budget ?? PEER_BLOCK_CHAR_BUDGET;
+  const prefixLength = opts.prefixLength ?? PEER_BLOCK_PREFIX.length;
+  if (!block || !Array.isArray(block.peer_agents) || block.peer_agents.length === 0) return block;
+  if (prefixLength + JSON.stringify(block).length <= budget) return block;
+
+  const rows = block.peer_agents.map((r) => (Array.isArray(r.dirs) ? { ...r, dirs: [...r.dirs] } : { ...r }));
+  const current = () => {
+    const dropped = block.peer_agents.length - rows.length;
+    const out = { ...block, peer_agents: rows, budget_trimmed: true };
+    if (dropped > 0) out.more_count = (block.more_count ?? 0) + dropped;
+    return out;
+  };
+  const over = () => prefixLength + JSON.stringify(current()).length > budget;
+
+  // Ties break toward the BOTTOM of the list in both passes below. Rows arrive
+  // sorted most-recently-active first, and the peer most likely to collide with
+  // your next write is the one that just wrote something — so the quiet sessions
+  // give up their hints before the busy ones do.
+  const widestFromTail = () => {
+    let widest = null;
+    for (const r of rows) {
+      if (Array.isArray(r.dirs) && r.dirs.length > 1 && (widest === null || r.dirs.length >= widest.dirs.length)) widest = r;
+    }
+    return widest;
+  };
+  const lastHolder = () => {
+    for (let i = rows.length - 1; i >= 0; i--) {
+      if (Array.isArray(rows[i].dirs) && rows[i].dirs.length > 0) return rows[i];
+    }
+    return null;
+  };
+
+  // 1 — shed hints from the widest row, keeping at least one hint on every row.
+  while (over()) {
+    const widest = widestFromTail();
+    if (widest === null) break;
+    widest.dirs.pop();
+    widest.dirs_more = (widest.dirs_more ?? 0) + 1;
+  }
+
+  // 2 — still over: give up the last hint rows are holding, quietest first.
+  while (over()) {
+    const holder = lastHolder();
+    if (holder === null) break;
+    holder.dirs.pop();
+    holder.dirs_more = (holder.dirs_more ?? 0) + 1;
+    if (holder.dirs.length === 0) delete holder.dirs;
+  }
+
+  // 3 — still over: drop rows from the tail. buildPeerAgentsBlock sorts most
+  // recently active first, so the quietest sessions go, and more_count says how
+  // many are missing.
+  while (over() && rows.length > 1) rows.pop();
+
+  return current();
+}
+
+/** Render the block as the single text line appended to tool responses. */
+export function formatPeerAgentsText(block) {
+  if (!block || !Array.isArray(block.peer_agents) || block.peer_agents.length === 0) return null;
+  return `${PEER_BLOCK_PREFIX}${JSON.stringify(fitPeerAgentsBlock(block))}`;
+}
+
+/**
+ * Render an explicit failure/staleness line — an agent must never read silence
+ * as "no peers" ([[HS-O8YN]]). "Confirmed empty" and "could not check" are
+ * opposite states and must never render identically. When a last-known-good
+ * block exists it is served WITH its age so staleness is visible, not implied.
+ */
+function formatUnavailableText(state) {
+  if (state.stale && state.block && Array.isArray(state.block.peer_agents) && state.block.peer_agents.length > 0) {
+    const ageSec = Math.max(0, Math.round(state.ageMs / 1000));
+    // Same budget applies here ([[HS-ZYPM]]) — this line has a LONGER prefix than
+    // the normal one, so it gets less room for rows, not more.
+    const prefix = `PEER AGENTS UNAVAILABLE (live check failed) — showing last known state from ${ageSec}s ago, may be stale: `;
+    return `${prefix}${JSON.stringify(fitPeerAgentsBlock(state.block, { prefixLength: prefix.length }))}`;
+  }
+  return 'PEER AGENTS UNAVAILABLE — could not reach the console to check for other live sessions. Peer presence is unknown, not confirmed empty.';
+}
+
+/**
+ * Dispatch wrapper ([[HS-GMNO]]): append the peer_agents line to an MCP tool
+ * result. Applied on EVERY tools/call response (unlike the once-per-session seat
+ * banner). Absolutely fail-open — a presence failure must never break a response,
+ * but per [[HS-O8YN]] it must never be SILENT either: a failed/timed-out check
+ * always appends an explicit "unavailable" line instead of returning `result`
+ * unchanged, so an agent can never mistake "could not check" for "no peers".
+ */
+export async function appendPeerPresence(result, opts = {}) {
+  try {
+    const state = await resolvePeerPresence(opts);
+    const line = state.ok ? formatPeerAgentsText(state.block) : formatUnavailableText(state);
+    if (!line) return result;
+    if (result && Array.isArray(result.content)) {
+      return { ...result, content: [...result.content, { type: 'text', text: `\n${line}` }] };
+    }
+    return result;
+  } catch {
+    return result;
+  }
+}