heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/response-budget.mjs

@@ -0,0 +1,348 @@
+// Byte budget for every MCP READ tool
+// ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]] under
+// [[HS-49AL-8KK5-EPIC-hot-row-cache-and-bounded-agent-tools]]).
+//
+// Before this module no byte budget existed anywhere in the MCP server: memory
+// recall bounded by COUNT and sliced, list tools that page
+// ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]], `list-tools.mjs`)
+// fit their own 8 KB page, and everything else returned whatever it had —
+// `heyspex_list_known_tags` once handed an agent 138 KB in one call
+// ([[HS-7QM6-1Q1C-DIAG-heyspex-list-known-tags-response-busts-t]]).
+//
+// The contract:
+//   - every read-shaped catalog tool (name matching {@link READ_TOOL_NAME_PATTERN})
+//     declares `budget: { max_bytes }` in `tool-catalog.mjs`
+//     ({@link DEFAULT_TOOL_BUDGET_BYTES} unless the tool says otherwise);
+//   - `tool-dispatch.mjs` runs every declared budget through
+//     {@link applyToolBudget} on the way out, so a tool that pages natively
+//     (list-tools, known-tags) is merely re-checked, and a tool that does NOT
+//     page is bounded anyway;
+//   - {@link enforceByteBudget} measures `Buffer.byteLength(JSON.stringify(result))`
+//     — the whole MCP result envelope, a strict superset of the text the agent
+//     reads — and when over budget drops trailing items from the payload's list,
+//     re-points `next_cursor` at the FIRST DROPPED item, and sets
+//     `truncated: true`. It never returns more than `max_bytes`: a payload with
+//     no list (or whose single remaining item is itself too big) has its
+//     longest strings cut with a marker, and as the last resort the payload is
+//     replaced by a tiny `RESPONSE_OVER_BUDGET` envelope.
+//
+// The generic `next_cursor` is a BUDGET cursor: an opaque base64url token the
+// dispatcher recognises on the way IN (`applyToolBudget` strips it, re-issues
+// the tool's own `after`, and resumes from the first dropped item), so a tool
+// with no native paging is still walkable to exhaustion one bounded page at a
+// time, and a tool WITH native paging keeps its own cursor untouched (the
+// budget cursor carries it inside).
+
+/** 48 000 bytes ≈ 12k tokens at ~4 bytes/token — the default ceiling for one read-tool reply. */
+export const DEFAULT_TOOL_BUDGET_BYTES = 48_000;
+
+/**
+ * Read-shaped tool names: the verb segment (after any namespace segment such as
+ * `design_`) is one of list / get / recall / search / next / ground.
+ * `heyspex_get_procedure`, `heyspex_design_get_pattern`, `heyspex_list_known_tags`,
+ * `heyspex_next_on_deck`, `heyspex_ground_plan` all match; `heyspex_claim_spec`
+ * does not.
+ */
+export const READ_TOOL_NAME_PATTERN = /^heyspex_(?:[a-z0-9]+_)*?(?:list|get|recall|search|next|ground)_/;
+
+/**
+ * Suffix-shaped reads (`heyspex_claim_list`, `heyspex_events_show`,
+ * `heyspex_settings_get`, …) — not in the task's prefix list, but every one of
+ * them returns rows or a record to an agent and so declares a budget too.
+ */
+export const READ_TOOL_SUFFIX_PATTERN = /_(?:list|show|get|load)$/;
+
+export function isReadShapedToolName(name) {
+  return READ_TOOL_NAME_PATTERN.test(name) || READ_TOOL_SUFFIX_PATTERN.test(name);
+}
+
+export const TRUNCATION_MARKER = '…[truncated: byte budget]';
+
+/** The measure every budget is checked against — the whole MCP result envelope. */
+export function measureResultBytes(result) {
+  return Buffer.byteLength(JSON.stringify(result), 'utf8');
+}
+
+// ── Budget cursor ────────────────────────────────────────────────────────────
+
+/**
+ * `{ key, at, index, after }` → opaque base64url token.
+ *   key   — the payload field holding the list that was trimmed
+ *   at    — identity ({@link itemIdentity}) of the FIRST DROPPED item, or null
+ *   index — absolute position of that item in the tool's untrimmed list
+ *   after — the tool's OWN `after` argument for this page (null when none),
+ *           re-issued verbatim when the walker comes back with this cursor
+ */
+export function encodeBudgetCursor({ key, at, index, after }) {
+  return Buffer.from(
+    JSON.stringify({ budget: 1, key: String(key), at: at == null ? null : String(at), index: Number(index) || 0, after: after ?? null }),
+    'utf8',
+  ).toString('base64url');
+}
+
+/** Decode a budget cursor; `null` for anything that is not one (a tool's own cursor, garbage, non-strings). */
+export function decodeBudgetCursor(cursor) {
+  if (typeof cursor !== 'string' || cursor.length === 0) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (parsed && typeof parsed === 'object' && parsed.budget === 1 && typeof parsed.key === 'string') {
+      return {
+        key: parsed.key,
+        at: typeof parsed.at === 'string' ? parsed.at : null,
+        index: Number.isFinite(parsed.index) && parsed.index >= 0 ? Math.floor(parsed.index) : 0,
+        after: typeof parsed.after === 'string' && parsed.after ? parsed.after : null,
+      };
+    }
+  } catch {
+    // not a budget cursor
+  }
+  return null;
+}
+
+/** Stable identity for a list item — the field a resume can find it by again. Null when nothing fits. */
+export function itemIdentity(item) {
+  if (item == null) return null;
+  if (typeof item !== 'object') return String(item);
+  for (const field of ['id', 'name', 'tag', 'key', 'path', 'spec_id']) {
+    const v = item[field];
+    if (typeof v === 'string' && v) return v;
+    if (typeof v === 'number') return String(v);
+  }
+  return null;
+}
+
+/** The top-level array field carrying the most bytes — the list a trim should shorten. */
+export function pickListKey(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  let best = null;
+  let bestBytes = -1;
+  for (const [key, value] of Object.entries(payload)) {
+    if (!Array.isArray(value) || value.length === 0) continue;
+    const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8');
+    if (bytes > bestBytes) {
+      best = key;
+      bestBytes = bytes;
+    }
+  }
+  return best;
+}
+
+function parsePayload(result) {
+  const block = result?.content?.[0];
+  if (!block || block.type !== 'text' || typeof block.text !== 'string') return { block: null, payload: null };
+  try {
+    const payload = JSON.parse(block.text);
+    return { block, payload: payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : null };
+  } catch {
+    return { block, payload: null };
+  }
+}
+
+function withPayload(result, block, payload, pretty) {
+  const text = pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+  return { ...result, content: [{ ...block, text }, ...result.content.slice(1)] };
+}
+
+function isPretty(text) {
+  return /^\s*[{[]\s*\n/.test(text);
+}
+
+/**
+ * Resume a tool's untrimmed result from a budget cursor: drop every item before
+ * the first-dropped item the cursor names. Returns the sliced result plus the
+ * absolute `offset` the slice started at (so the NEXT budget cursor's `index`
+ * stays absolute). A cursor whose list key does not exist in the payload
+ * resumes nothing (offset 0) rather than failing — the walker still terminates
+ * because the page is re-fitted below.
+ */
+export function resumeFromBudgetCursor(result, cursor) {
+  const { block, payload } = parsePayload(result);
+  if (!block || !payload || !Array.isArray(payload[cursor.key])) return { result, offset: 0 };
+  const list = payload[cursor.key];
+  let offset = -1;
+  if (cursor.at != null) offset = list.findIndex((item) => itemIdentity(item) === cursor.at);
+  if (offset === -1) offset = Math.min(cursor.index, list.length);
+  const next = { ...payload, [cursor.key]: list.slice(offset) };
+  return { result: withPayload(result, block, next, isPretty(block.text)), offset };
+}
+
+// ── Enforcement ──────────────────────────────────────────────────────────────
+
+/** Largest `n` in `[lo, hi]` for which `fits(n)` holds (`fits` is monotone: smaller n ⇒ fewer bytes). */
+function largestFitting(lo, hi, fits) {
+  let best = lo - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    if (fits(mid)) {
+      best = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+/** Walk a payload for its string leaves (depth-limited) — `[path, length]`, longest first. */
+function longestStrings(value, path = [], depth = 0, out = []) {
+  if (depth > 4 || value == null) return out;
+  if (typeof value === 'string') {
+    out.push({ path, length: value.length });
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => longestStrings(v, [...path, i], depth + 1, out));
+  } else if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) longestStrings(v, [...path, k], depth + 1, out);
+  }
+  return out;
+}
+
+function getAt(obj, path) {
+  return path.reduce((acc, k) => (acc == null ? undefined : acc[k]), obj);
+}
+
+function setAt(obj, path, value) {
+  const clone = Array.isArray(obj) ? [...obj] : { ...obj };
+  if (path.length === 1) {
+    clone[path[0]] = value;
+    return clone;
+  }
+  clone[path[0]] = setAt(obj[path[0]], path.slice(1), value);
+  return clone;
+}
+
+function overBudgetEnvelope(result, { tool, bytes, maxBytes }) {
+  const text = JSON.stringify({
+    error: 'RESPONSE_OVER_BUDGET',
+    tool: tool ?? null,
+    truncated: true,
+    bytes,
+    max_bytes: maxBytes,
+    message: `The tool reply was ${bytes} bytes against a ${maxBytes}-byte budget and could not be trimmed to fit. Narrow the call (filters, a smaller limit, compact mode) and retry.`,
+  });
+  return { ...(result?.isError ? { isError: true } : {}), content: [{ type: 'text', text }] };
+}
+
+/**
+ * Bound one MCP tool result to `maxBytes` (measured on the whole envelope).
+ *
+ * @param result   the MCP result `{ content: [{ type: 'text', text }], isError? }`
+ * @param options.maxBytes     the budget ({@link DEFAULT_TOOL_BUDGET_BYTES} when omitted)
+ * @param options.listKey      the payload field to trim; auto-detected ({@link pickListKey}) when omitted
+ * @param options.tool         tool name, recorded in the trim envelope
+ * @param options.after        the tool's own `after` arg for this page — carried inside the budget cursor
+ * @param options.indexOffset  absolute index of the payload list's first item (a resumed page)
+ * @returns {{ result: object, bytes: number, truncated: boolean, dropped: number }}
+ */
+export function enforceByteBudget(result, options = {}) {
+  const maxBytes = Number.isFinite(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : DEFAULT_TOOL_BUDGET_BYTES;
+  const tool = options.tool ?? null;
+  if (!result || !Array.isArray(result.content)) {
+    return { result, bytes: measureResultBytes(result ?? null), truncated: false, dropped: 0 };
+  }
+  let bytes = measureResultBytes(result);
+  if (bytes <= maxBytes) return { result, bytes, truncated: false, dropped: 0 };
+
+  const { block, payload } = parsePayload(result);
+  let dropped = 0;
+
+  if (block && payload) {
+    const pretty = isPretty(block.text);
+    let current = payload;
+
+    // 1. Drop trailing list items; the cursor points at the first dropped one.
+    const key = options.listKey && Array.isArray(payload[options.listKey]) ? options.listKey : pickListKey(payload);
+    if (key && Array.isArray(current[key]) && current[key].length > 1) {
+      const list = current[key];
+      const offset = Number(options.indexOffset) || 0;
+      const shaped = (n) => ({
+        ...current,
+        [key]: list.slice(0, n),
+        next_cursor: encodeBudgetCursor({ key, at: itemIdentity(list[n]), index: offset + n, after: options.after ?? null }),
+        truncated: true,
+        budget: { max_bytes: maxBytes, list_key: key, returned: n, dropped: list.length - n },
+      });
+      const fits = (n) => measureResultBytes(withPayload(result, block, shaped(n), pretty)) <= maxBytes;
+      // Never an empty page with a cursor: at least one item stays, and if that
+      // lone item still does not fit the string cut below handles it.
+      const keep = Math.max(1, largestFitting(1, list.length - 1, fits));
+      current = shaped(keep);
+      dropped = list.length - keep;
+      bytes = measureResultBytes(withPayload(result, block, current, pretty));
+    }
+
+    // 2. Still over: cut the longest strings, longest first, until it fits.
+    if (bytes > maxBytes) {
+      current = { ...current, truncated: true, budget: { ...(current.budget ?? {}), max_bytes: maxBytes, strings_cut: 0 } };
+      let guard = 0;
+      while (bytes > maxBytes && guard < 64) {
+        guard += 1;
+        const candidates = longestStrings(current).filter((c) => c.length > TRUNCATION_MARKER.length + 8 && c.path[0] !== 'next_cursor');
+        if (candidates.length === 0) break;
+        candidates.sort((a, b) => b.length - a.length);
+        const target = candidates[0];
+        const value = getAt(current, target.path);
+        const overshoot = bytes - maxBytes;
+        // Cut generously: the overshoot plus the marker, but never below 8 chars of the original.
+        const keepChars = Math.max(8, value.length - overshoot - TRUNCATION_MARKER.length);
+        current = setAt(current, target.path, value.slice(0, keepChars) + TRUNCATION_MARKER);
+        current.budget = { ...current.budget, strings_cut: (current.budget.strings_cut ?? 0) + 1 };
+        bytes = measureResultBytes(withPayload(result, block, current, pretty));
+      }
+    }
+
+    if (bytes <= maxBytes) {
+      return { result: withPayload(result, block, current, pretty), bytes, truncated: true, dropped };
+    }
+  } else if (block) {
+    // 3. Non-JSON text: cut the text itself to fit.
+    const text = block.text;
+    const fitsText = (n) => measureResultBytes({ ...result, content: [{ ...block, text: text.slice(0, n) + TRUNCATION_MARKER }, ...result.content.slice(1)] }) <= maxBytes;
+    const keep = largestFitting(0, text.length, fitsText);
+    if (keep >= 0) {
+      const cut = { ...result, content: [{ ...block, text: text.slice(0, keep) + TRUNCATION_MARKER }, ...result.content.slice(1)] };
+      return { result: cut, bytes: measureResultBytes(cut), truncated: true, dropped: 0 };
+    }
+  }
+
+  // 4. Last resort — the envelope is a few hundred bytes and always fits.
+  const envelope = overBudgetEnvelope(result, { tool, bytes, maxBytes });
+  return { result: envelope, bytes: measureResultBytes(envelope), truncated: true, dropped };
+}
+
+/**
+ * The dispatcher's hook: run `invoke(args)` for a tool that declares `budget`,
+ * resuming from a budget cursor on the way in and enforcing the budget on the
+ * way out. A tool without a budget is invoked untouched. `invoke` may return a
+ * Promise (several handlers are async) — the result is unwrapped either way.
+ */
+export function applyToolBudget(name, args, invoke, budget) {
+  const maxBytes = Number(budget?.max_bytes);
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return invoke(args);
+
+  let effectiveArgs = args ?? {};
+  let resume = null;
+  if (typeof effectiveArgs.after === 'string') {
+    resume = decodeBudgetCursor(effectiveArgs.after);
+    if (resume) {
+      effectiveArgs = { ...effectiveArgs };
+      if (resume.after) effectiveArgs.after = resume.after;
+      else delete effectiveArgs.after;
+    }
+  }
+
+  const finish = (raw) => {
+    let result = raw;
+    let indexOffset = 0;
+    if (resume) ({ result, offset: indexOffset } = resumeFromBudgetCursor(result, resume));
+    return enforceByteBudget(result, {
+      maxBytes,
+      listKey: budget.list_key,
+      tool: name,
+      after: typeof effectiveArgs.after === 'string' ? effectiveArgs.after : null,
+      indexOffset,
+    }).result;
+  };
+
+  const raw = invoke(effectiveArgs);
+  return raw && typeof raw.then === 'function' ? raw.then(finish) : finish(raw);
+}

package/vendor/heyspex-mcp/review-focus.mjs

@@ -5,6 +5,23 @@
  * Mirrors `.heyspex/focus.yaml` (build pipeline) and `.heyspex/research-focus.yaml`
  * (research pipeline). Honored unconditionally when present, same semantics as
  * [[focus-yaml-always-wins-in-hs-next]].
+ *
+ * CLOUD WRITE MODE ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * this module is deliberately NOT routed through the console, and that is a
+ * decision rather than an omission. The pin it writes is LOCAL MACHINE STATE,
+ * not vault content — it lives in the repo's dot-directory, never under
+ * `specs/`, carries no id/type/frontmatter contract, and is not indexed by
+ * anything. It is therefore not a split brain the way a stray `specs/*.md`
+ * would be: a pin is per-workstation by design, and two machines are SUPPOSED
+ * to be able to hold different ones. HS-KR16 §Scope made exactly this call for
+ * the promote-research review-gate markers in the same dot-directory.
+ *
+ * The corollary: because it is not vault content, it also has no spec `type`
+ * and therefore no `POST /api/specs` route it could be filed through — routing
+ * it would mean inventing a type, which is the thing
+ * `CLOUD_MODE_UNSUPPORTED_WRITE` exists to refuse. Keeping the disk write is
+ * the correct behaviour in BOTH modes; it is not degraded and does not need to
+ * be reported.
  */
 
 import {
@@ -14,8 +31,10 @@ import {
   mkdirSync,
   rmSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute, resolve, sep } from 'node:path';
 import { parseSimpleFocusYaml } from './capture-focus.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
 
 export function reviewFocusPath(vaultRoot) {
   return join(vaultRoot, '.heyspex', 'review-focus.yaml');
@@ -36,6 +55,11 @@ export function writeReviewFocus(vaultRoot, { specId, reason }) {
     return { error: 'MISSING_SPEC_ID', message: 'spec_id is required' };
   }
   const dir = join(vaultRoot, '.heyspex');
+  try {
+    assertPathUnderRoot(vaultRoot, dir, 'review-focus write');
+  } catch (err) {
+    return { error: 'BAD_VAULT_ROOT', message: err.message };
+  }
   mkdirSync(dir, { recursive: true });
   const lines = [
     '# HeySpex review-on-deck — MCP /hs-review ([[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]])',

package/vendor/heyspex-mcp/roadmap-default.mjs

@@ -0,0 +1,70 @@
+// Per-vault default roadmap resolution. The MCP used to hardcode the HeySpex
+// platform vault's roadmap id ('HS-ROADMAP-PRODUCT'), so every customer vault
+// (whose roadmap has a different id, e.g. the `hs init` starter
+// 'HS-START-ROADMAP') failed `heyspex_next_on_deck` with ROADMAP_NOT_FOUND.
+//
+// Precedence (explicit `roadmap_id` arg is applied by callers, above this):
+//   HEYSPEX_ROADMAP_ID env > the vault's own `type: roadmap` spec >
+//   'HS-ROADMAP-PRODUCT' (last resort).
+// Resolved per call from the vault root of THAT call: one MCP process can
+// serve several vaults, so nothing here is cached.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+
+export const PLATFORM_ROADMAP_ID = 'HS-ROADMAP-PRODUCT';
+
+const SCAN_DIRS = ['specs/roadmaps', 'specs/roadmap', 'specs'];
+
+function headFields(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return null;
+  const grab = (k) => {
+    const r = new RegExp('^' + k + ':[ \t]*(.+?)[ \t\r]*$', 'm').exec(m[1]);
+    return r ? r[1].replace(/^["']|["']$/g, '') : null;
+  };
+  return { type: grab('type'), id: grab('id') };
+}
+
+/** All `type: roadmap` spec ids found on disk under the vault's specs/. */
+export function listVaultRoadmapIds(vaultRoot) {
+  const ids = new Set();
+  if (!vaultRoot) return [];
+  for (const dir of SCAN_DIRS) {
+    const abs = join(vaultRoot, dir);
+    if (!existsSync(abs)) continue;
+    let names;
+    try {
+      names = readdirSync(abs);
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      if (!n.endsWith('.md')) continue;
+      const f = headFields(join(abs, n));
+      if (f && f.type === 'roadmap' && f.id) ids.add(f.id);
+    }
+  }
+  return [...ids].sort();
+}
+
+/**
+ * @returns {{ id: string, source: 'env'|'vault'|'vault-multiple'|'fallback', candidates?: string[] }}
+ */
+export function resolveDefaultRoadmap(vaultRoot, env = process.env) {
+  const fromEnv = env.HEYSPEX_ROADMAP_ID?.trim();
+  if (fromEnv) return { id: fromEnv, source: 'env' };
+  const ids = listVaultRoadmapIds(vaultRoot);
+  if (ids.length === 1) return { id: ids[0], source: 'vault' };
+  if (ids.length > 1) {
+    const id = ids.includes(PLATFORM_ROADMAP_ID) ? PLATFORM_ROADMAP_ID : ids[0];
+    return { id, source: 'vault-multiple', candidates: ids };
+  }
+  return { id: PLATFORM_ROADMAP_ID, source: 'fallback' };
+}