heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/http-transport.mjs

@@ -0,0 +1,300 @@
+/**
+ * http-transport.mjs — MCP Streamable HTTP transport, JSON-response mode.
+ *
+ * A thin, dependency-free JSON-RPC 2.0 front for the EXISTING tool dispatch
+ * (`tool-dispatch.mjs#dispatchHeySpexTool`), built for the first remote MCP
+ * endpoint (`POST /api/mcp` on the console, WP6 of the cloud-first track).
+ * `cli.mjs` remains the stdio wiring; this module is the HTTP wiring. Neither
+ * knows about tools — both hand every `tools/call` to the same dispatch.
+ *
+ * Scope (deliberately small):
+ *   - methods: initialize, notifications/*, ping, tools/list, tools/call
+ *   - single messages AND batches (JSON-RPC arrays)
+ *   - stateless: `initialize` mints a session id, later calls echo the
+ *     client's `Mcp-Session-Id`; nothing is kept server-side
+ *   - JSON responses only (`application/json`). SSE streaming is NOT
+ *     implemented: the server never pushes notifications or progress, so a
+ *     plain JSON reply is a complete, spec-valid response for every method
+ *     here. Clients that accept only `text/event-stream` still get JSON.
+ *
+ * The handler is a factory (`createRemoteMcpHandler`) fed its dependencies —
+ * `dispatch`, the visible `tools`, the allowlist predicate — so this file
+ * never imports the heavy dispatch graph and stays unit-testable in
+ * isolation. Every `tools/call` runs inside `runWithRequestContext`, which is
+ * how the caller's own console origin + bearer reach `console-transport.mjs`
+ * without touching `process.env` (see request-context.mjs).
+ */
+import { randomUUID } from 'node:crypto';
+
+import { runWithRequestContext } from './request-context.mjs';
+
+export const JSONRPC_VERSION = '2.0';
+
+/** Protocol revisions this transport speaks; the client's pick is echoed when listed. */
+export const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+export const DEFAULT_PROTOCOL_VERSION = '2025-03-26';
+
+export const JSONRPC_ERROR = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+});
+
+/** Error code for a tool that exists in the catalog but is not served remotely. */
+export const TOOL_NOT_AVAILABLE_REMOTELY = 'TOOL_NOT_AVAILABLE_REMOTELY';
+
+export function negotiateProtocolVersion(requested) {
+  return typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+    ? requested
+    : DEFAULT_PROTOCOL_VERSION;
+}
+
+export function newSessionId() {
+  return randomUUID();
+}
+
+export function jsonRpcError(id, code, message, data) {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id: id === undefined ? null : id,
+    error: { code, message, ...(data !== undefined ? { data } : {}) },
+  };
+}
+
+export function jsonRpcResult(id, result) {
+  return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+
+/** The body to send when the request body was not valid JSON at all. */
+export function parseErrorBody() {
+  return jsonRpcError(null, JSONRPC_ERROR.PARSE_ERROR, 'Parse error: request body is not valid JSON');
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidId(id) {
+  return typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
+}
+
+/** Strip the catalog-only `budget` field: it is a server contract, not MCP wire shape. */
+export function toWireTool(tool) {
+  const { budget: _budget, ...wire } = tool;
+  return wire;
+}
+
+/**
+ * Human-readable refusal for a catalog tool that is not on the remote surface.
+ * Returned as a JSON-RPC `-32602` (the MCP convention for an unknown tool) so
+ * the client surfaces it as a protocol error rather than a tool result.
+ */
+export function toolNotAvailableRemotelyError(id, name) {
+  return jsonRpcError(
+    id,
+    JSONRPC_ERROR.INVALID_PARAMS,
+    `Tool "${name}" is not available on the remote HeySpex MCP endpoint. It reads or writes the local vault checkout (disk/git), so it needs the local stdio server: install the heyspex package and add it with \`claude mcp add heyspex heyspex-mcp\` (see docs/mcp-client-config.md).`,
+    { error: TOOL_NOT_AVAILABLE_REMOTELY, tool: name },
+  );
+}
+
+/**
+ * @typedef {object} RemoteMcpDeps
+ * @property {(name: string, args: Record<string, unknown>, vaultRoot: string, config: object) => unknown} dispatch
+ *   The tool dispatch (`dispatchHeySpexTool`). May return a value or a Promise.
+ * @property {Array<{ name: string, [k: string]: unknown }>} tools
+ *   The tools to advertise from `tools/list` — already reduced to the remote surface.
+ * @property {(name: string) => boolean} [isToolAllowed]
+ *   Allowlist predicate for `tools/call` (default: membership in `tools`).
+ * @property {(name: string) => boolean} [isKnownTool]
+ *   Whether a name exists in the FULL catalog — distinguishes "needs the local
+ *   server" from "no such tool" (default: same as `isToolAllowed`).
+ * @property {{ name: string, version: string }} serverInfo
+ * @property {string} [instructions]
+ * @property {string} vaultRoot
+ *   Passed through to `dispatch`. For the remote endpoint this is a path that
+ *   does not exist: every allowlisted handler works via the console API in the
+ *   neon read tier and never touches it.
+ * @property {object} [config] Passed through to `dispatch` (default: `{ vaultRoot }`).
+ */
+
+/**
+ * @typedef {object} RemoteMcpCallContext
+ * @property {string|null} [sessionId] The client's `Mcp-Session-Id`, if any.
+ * @property {string} [consoleUrl] Origin the in-process handlers should call back to (the deployment itself).
+ * @property {Record<string, string>} [authHeader] The caller's own credential to forward on those calls.
+ * @property {string} [agentName] Default `agent` for tools whose schema declares one.
+ */
+
+/**
+ * Build the remote handler. Returns `{ handleMessage, handleBody }`:
+ *   - `handleMessage(message, ctx)` → one JSON-RPC response object, or `null`
+ *     for a notification / client response (nothing to send back)
+ *   - `handleBody(parsedBody, ctx)` → `{ status, body, sessionId }` for a
+ *     single message or a batch; `status` 202 + `body` null when there is
+ *     nothing to send (notification-only input)
+ *
+ * @param {RemoteMcpDeps} deps
+ */
+export function createRemoteMcpHandler(deps) {
+  const {
+    dispatch,
+    tools,
+    serverInfo,
+    instructions,
+    vaultRoot,
+  } = deps;
+  if (typeof dispatch !== 'function') throw new TypeError('createRemoteMcpHandler: dispatch is required');
+  if (!Array.isArray(tools)) throw new TypeError('createRemoteMcpHandler: tools must be an array');
+  if (typeof vaultRoot !== 'string' || !vaultRoot) throw new TypeError('createRemoteMcpHandler: vaultRoot is required');
+
+  const toolsByName = new Map(tools.map((t) => [t.name, t]));
+  const isToolAllowed = deps.isToolAllowed ?? ((name) => toolsByName.has(name));
+  const isKnownTool = deps.isKnownTool ?? isToolAllowed;
+  const config = deps.config ?? { vaultRoot };
+  const wireTools = tools.map(toWireTool);
+
+  function initializeResult(params) {
+    return {
+      protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
+      // No listChanged: the remote surface is fixed (no progressive loader),
+      // and JSON-response mode has no channel to push a notification anyway.
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: serverInfo?.name ?? 'heyspex', version: serverInfo?.version ?? '0.0.0-unknown' },
+      ...(instructions ? { instructions } : {}),
+    };
+  }
+
+  /**
+   * Fill `session_id` / `agent` from the transport when the tool's schema
+   * declares them and the caller left them out — a remote client has no
+   * CLAUDE_CODE_SESSION_ID env for `detectAgentIdentity` to find, so without
+   * this every remote claim would read as "External agent · local".
+   */
+  function withIdentityDefaults(tool, args, ctx) {
+    const props = tool?.inputSchema?.properties;
+    if (!isPlainObject(props)) return args;
+    const out = { ...args };
+    if ('session_id' in props && out.session_id === undefined && ctx?.sessionId) {
+      out.session_id = ctx.sessionId;
+    }
+    if ('agent' in props && out.agent === undefined && ctx?.agentName) {
+      out.agent = ctx.agentName;
+    }
+    return out;
+  }
+
+  async function callTool(id, params, ctx) {
+    const name = params?.name;
+    if (typeof name !== 'string' || !name.trim()) {
+      return jsonRpcError(id, JSONRPC_ERROR.INVALID_PARAMS, 'tools/call requires params.name (string)');
+    }
+    if (!isToolAllowed(name)) {
+      return isKnownTool(name)
+        ? toolNotAvailableRemotelyError(id, name)
+        : jsonRpcError(id, JSONRPC_ERROR.INVALID_PARAMS, `Unknown tool: ${name}`, { tool: name });
+    }
+    const rawArgs = params?.arguments;
+    if (rawArgs !== undefined && !isPlainObject(rawArgs)) {
+      return jsonRpcError(id, JSONRPC_ERROR.INVALID_PARAMS, 'tools/call params.arguments must be an object');
+    }
+    const args = withIdentityDefaults(toolsByName.get(name), rawArgs ?? {}, ctx);
+    const requestContext = {
+      ...(ctx?.consoleUrl ? { consoleUrl: ctx.consoleUrl } : {}),
+      ...(ctx?.authHeader ? { authHeader: ctx.authHeader } : {}),
+    };
+    try {
+      const result = await runWithRequestContext(requestContext, () => dispatch(name, args, vaultRoot, config));
+      if (!isPlainObject(result) || !Array.isArray(result.content)) {
+        return jsonRpcError(id, JSONRPC_ERROR.INTERNAL_ERROR, `Tool "${name}" returned a malformed result`);
+      }
+      return jsonRpcResult(id, result);
+    } catch (err) {
+      return jsonRpcError(
+        id,
+        JSONRPC_ERROR.INTERNAL_ERROR,
+        `Tool "${name}" failed: ${err?.message ?? String(err)}`,
+        { tool: name },
+      );
+    }
+  }
+
+  /**
+   * @param {unknown} message
+   * @param {RemoteMcpCallContext} [ctx]
+   * @returns {Promise<object|null>}
+   */
+  async function handleMessage(message, ctx = {}) {
+    if (!isPlainObject(message) || message.jsonrpc !== JSONRPC_VERSION) {
+      return jsonRpcError(null, JSONRPC_ERROR.INVALID_REQUEST, 'Invalid Request: expected a JSON-RPC 2.0 message');
+    }
+    const { id, method, params } = message;
+
+    // A response from the client (to a server request) — we never send
+    // requests, so there is nothing to correlate. Ignore.
+    if (method === undefined && ('result' in message || 'error' in message)) return null;
+
+    if (typeof method !== 'string') {
+      return jsonRpcError(isValidId(id) ? id : null, JSONRPC_ERROR.INVALID_REQUEST, 'Invalid Request: method must be a string');
+    }
+
+    // Notifications carry no id and get no response (notifications/initialized, cancelled, ...).
+    if (id === undefined || id === null) return null;
+
+    if (!isValidId(id)) {
+      return jsonRpcError(null, JSONRPC_ERROR.INVALID_REQUEST, 'Invalid Request: id must be a string or number');
+    }
+    if (params !== undefined && !isPlainObject(params)) {
+      return jsonRpcError(id, JSONRPC_ERROR.INVALID_PARAMS, 'params must be an object');
+    }
+
+    switch (method) {
+      case 'initialize':
+        return jsonRpcResult(id, initializeResult(params));
+      case 'ping':
+        return jsonRpcResult(id, {});
+      case 'tools/list':
+        return jsonRpcResult(id, { tools: wireTools });
+      case 'tools/call':
+        return callTool(id, params, ctx);
+      default:
+        return jsonRpcError(id, JSONRPC_ERROR.METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+  }
+
+  /**
+   * @param {unknown} parsed The JSON-decoded request body (object or array).
+   * @param {RemoteMcpCallContext} [ctx]
+   * @returns {Promise<{ status: number, body: object|object[]|null, sessionId: string|null }>}
+   */
+  async function handleBody(parsed, ctx = {}) {
+    const messages = Array.isArray(parsed) ? parsed : [parsed];
+    if (Array.isArray(parsed) && parsed.length === 0) {
+      return {
+        status: 400,
+        body: jsonRpcError(null, JSONRPC_ERROR.INVALID_REQUEST, 'Invalid Request: empty batch'),
+        sessionId: ctx.sessionId ?? null,
+      };
+    }
+
+    // `initialize` mints the session id the client will echo from then on;
+    // any other message just echoes what the client sent (stateless server).
+    const initializes = messages.some((m) => isPlainObject(m) && m.method === 'initialize');
+    const sessionId = initializes ? newSessionId() : (ctx.sessionId ?? null);
+    const callCtx = { ...ctx, sessionId };
+
+    const responses = [];
+    for (const message of messages) {
+      const response = await handleMessage(message, callCtx);
+      if (response !== null) responses.push(response);
+    }
+
+    if (responses.length === 0) return { status: 202, body: null, sessionId };
+    if (Array.isArray(parsed)) return { status: 200, body: responses, sessionId };
+    return { status: 200, body: responses[0], sessionId };
+  }
+
+  return { handleMessage, handleBody };
+}

package/vendor/heyspex-mcp/list-tools.mjs

@@ -0,0 +1,257 @@
+// Keyset paging + byte budget for every MCP tool that lists specs
+// ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]] under
+// [[HS-0R2X-8KK5-EPIC-keyset-paging-on-every-list-and-agent]]).
+//
+// The contract every list-shaped tool in the registry follows:
+//   - accepts `limit` (clamped to the tool's max) plus an opaque `after`
+//     cursor, and hands back ONE page under `<rows_key>` plus `next_cursor`
+//     (a string when more rows exist, `null` on the last page — the field is
+//     always present);
+//   - never a total count — the response says what it returned, not how many
+//     rows exist ([[mcp-tool-response-size-budget]]: ~2k tokens per list call);
+//   - the serialized response stays under the tool's byte budget: when a page
+//     would exceed it, rows are dropped from the END of the page and
+//     `next_cursor` is re-pointed at the last row kept, so the caller loses
+//     nothing — it just follows the cursor. The cursor is never dropped.
+//
+// `LIST_SPEC_TOOLS` is the registry `list-tools.byte-budget.test.mjs` walks:
+// every tool named here must declare `limit` + `after` in its catalog schema
+// and prove the page + budget behaviour against a fixture vault. A tool
+// whose name looks list-shaped but whose rows are NOT specs is classified in
+// `NON_SPEC_LIST_TOOLS` with a reason, so a new list tool that is neither
+// fails the registry test until someone classifies it.
+//
+// Cursor shape mirrors the console's keyset endpoint
+// (`spex-console/src/lib/specs/list-query.ts`): base64url JSON over the sort
+// key + the id tie-breaker, opaque to callers, fails closed on garbage.
+
+/** ~2k tokens ([[mcp-tool-response-size-budget]]) at ~4 bytes per token. */
+export const LIST_TOOL_BYTE_BUDGET = 8 * 1024;
+
+/**
+ * Every MCP tool whose rows are specs. Keys are catalog tool names.
+ *   rows_key      — the response field carrying the page
+ *   default_limit — page size when the caller passes no `limit`
+ *   max_limit     — hard clamp on a caller's `limit`
+ *   byte_budget   — ceiling on `Buffer.byteLength(content[0].text)`
+ */
+export const LIST_SPEC_TOOLS = Object.freeze({
+  heyspex_recall_memories: Object.freeze({
+    rows_key: 'memories',
+    default_limit: 10,
+    max_limit: 30,
+    byte_budget: LIST_TOOL_BYTE_BUDGET,
+  }),
+  heyspex_list_procedures: Object.freeze({
+    rows_key: 'procedures',
+    default_limit: 10,
+    max_limit: 50,
+    byte_budget: LIST_TOOL_BYTE_BUDGET,
+  }),
+});
+
+/**
+ * Tools whose NAME reads as a list but whose rows are not specs — exempt from
+ * the spec-paging contract, each with the reason on record. The registry test
+ * requires every list-looking catalog tool to appear in exactly one of the two
+ * maps.
+ */
+export const NON_SPEC_LIST_TOOLS = Object.freeze({
+  heyspex_list_known_tags: 'tag vocabulary with per-tag counts (GET /api/scheduler/known-tags) — not spec rows',
+  heyspex_claim_list: 'active claim rows from the Neon control plane — not spec rows',
+  heyspex_design_list_patterns: 'design-system registry entries — not spec rows',
+  heyspex_list_recipes: 'workflow-recipe entries — not spec rows',
+  heyspex_fleet_queue_list: 'fleet-queue task rows (bearer-authed) — not spec rows',
+  heyspex_settings_list: 'settings registry entries — not spec rows',
+  heyspex_hooks_list: 'active hook configuration — not spec rows',
+  heyspex_events_show: 'per-spec audit-event rows, already `limit`-capped — not spec rows',
+  heyspex_milestone_show: 'ONE milestone plus its needs-breakdown shape (GET /api/specs/:id) — a single spec, not a list',
+  heyspex_evidence_show: 'evidence rows attached to ONE spec — not a list of specs',
+  heyspex_load_tools: 'progressive-disclosure tool-surface loader — not a list of anything in the vault',
+});
+
+/** The tool names the registry test treats as "list-shaped by name". */
+export const LIST_SHAPED_NAME_PATTERN = /^heyspex_(list_|recall_|load_)|_list$|_show$/;
+
+/**
+ * Cursors are opaque to callers by design — malformed input fails closed as
+ * "bad cursor", never a silent restart from page 1 or a full re-scan.
+ */
+export class InvalidListCursorError extends Error {
+  constructor() {
+    super('invalid or corrupted `after` cursor — pass a `next_cursor` value from a prior page, or omit it for page 1');
+    this.name = 'INVALID_CURSOR';
+  }
+}
+
+/** `{ k, id }` → opaque base64url string. `k` is the sort key, `id` the tie-breaker. */
+export function encodeListCursor({ k, id }) {
+  return Buffer.from(JSON.stringify({ k: String(k ?? ''), id: String(id ?? '') }), 'utf8').toString('base64url');
+}
+
+export function decodeListCursor(cursor) {
+  if (typeof cursor !== 'string' || cursor.length === 0) throw new InvalidListCursorError();
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (parsed && typeof parsed === 'object' && typeof parsed.k === 'string' && typeof parsed.id === 'string') {
+      return { k: parsed.k, id: parsed.id };
+    }
+  } catch {
+    // fall through
+  }
+  throw new InvalidListCursorError();
+}
+
+/** Clamp a caller's `limit` into `[1, max_limit]`, defaulting when absent/invalid. */
+export function resolvePageLimit(raw, { default_limit, max_limit }) {
+  const n = Number(raw);
+  const wanted = Number.isFinite(n) && n > 0 ? Math.floor(n) : default_limit;
+  return Math.max(1, Math.min(wanted, max_limit));
+}
+
+function compareKeyset(a, b) {
+  return a.k.localeCompare(b.k) || a.id.localeCompare(b.id);
+}
+
+/**
+ * One page of an in-memory row set on the keyset contract.
+ *
+ * Rows are sorted by `(keyOf(row), idOf(row))` — both must be immutable for
+ * the row's lifetime, or an edit would move it between pages — then the page
+ * is the first `limit` rows strictly AFTER the cursor position. Fetches
+ * nothing beyond what the caller already loaded; the disk tier has no index
+ * to seek (retiring that whole-vault read is
+ * [[HS-49AL-8KK5-EPIC-hot-row-cache-and-bounded-agent-tools]]'s job).
+ *
+ * @returns {{ rows: any[], next_cursor: string|null }}
+ */
+export function paginateRowsKeyset(rows, { limit, after, keyOf, idOf }) {
+  const keyed = rows.map((row) => ({ row, k: String(keyOf(row) ?? ''), id: String(idOf(row) ?? '') }));
+  keyed.sort(compareKeyset);
+  let start = 0;
+  if (after) {
+    const cursor = decodeListCursor(after);
+    start = keyed.findIndex((entry) => compareKeyset(entry, cursor) > 0);
+    if (start === -1) return { rows: [], next_cursor: null };
+  }
+  const page = keyed.slice(start, start + limit);
+  const hasMore = start + limit < keyed.length;
+  const last = page[page.length - 1];
+  return {
+    rows: page.map((entry) => entry.row),
+    next_cursor: hasMore && last ? encodeListCursor({ k: last.k, id: last.id }) : null,
+  };
+}
+
+/** The serializer every list tool's `content[0].text` goes through — the budget is measured on exactly this. */
+export function serializeListResult(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Shrink a page until its serialized form fits `byte_budget`.
+ *
+ * Drops rows from the END of `result[rows_key]` and re-points `next_cursor`
+ * at the last row kept (via `cursorFor(row)`), so the dropped rows are the
+ * first rows of the NEXT page — nothing is lost, the cursor is never dropped.
+ * `page.budget_trimmed: true` marks a trim. The last row is never dropped:
+ * a single row that alone exceeds the budget is returned as-is (better one
+ * over-budget row than an empty page with no way forward).
+ *
+ * @returns {{ result: object, text: string, bytes: number }}
+ */
+export function fitPageToByteBudget(result, { rows_key, byte_budget, cursorFor }) {
+  let current = result;
+  let text = serializeListResult(current);
+  let bytes = Buffer.byteLength(text, 'utf8');
+  while (bytes > byte_budget && Array.isArray(current[rows_key]) && current[rows_key].length > 1) {
+    const kept = current[rows_key].slice(0, -1);
+    const last = kept[kept.length - 1];
+    current = {
+      ...current,
+      [rows_key]: kept,
+      next_cursor: cursorFor(last),
+      page: { ...(current.page ?? {}), returned: kept.length, budget_trimmed: true },
+    };
+    text = serializeListResult(current);
+    bytes = Buffer.byteLength(text, 'utf8');
+  }
+  return { result: current, text, bytes };
+}
+
+/**
+ * The whole contract in one call, for a tool that already has its filtered
+ * rows in memory: clamp `limit`, decode `after`, page, attach the `page`
+ * envelope, then fit to the byte budget.
+ *
+ * Returns `{ result, text, bytes }` on success or `{ error }` (an
+ * `INVALID_CURSOR` payload shaped like every other tool error) when `after`
+ * does not decode. `extra` fields are spread onto the result AFTER the page
+ * (e.g. `filters_applied`), so a tool keeps its existing companion fields.
+ */
+export function pageListToolResult(toolName, rows, args = {}, { keyOf, idOf, extra = {} }) {
+  const spec = LIST_SPEC_TOOLS[toolName];
+  if (!spec) throw new Error(`pageListToolResult: "${toolName}" is not in LIST_SPEC_TOOLS`);
+  const limit = resolvePageLimit(args.limit, spec);
+  let page;
+  try {
+    page = paginateRowsKeyset(rows, { limit, after: args.after, keyOf, idOf });
+  } catch (err) {
+    if (err instanceof InvalidListCursorError) {
+      return { error: { error: 'INVALID_CURSOR', message: err.message, tool: toolName } };
+    }
+    throw err;
+  }
+  return finishPagedListToolResult(toolName, { rows: page.rows, next_cursor: page.next_cursor, limit }, { keyOf, idOf, extra });
+}
+
+/**
+ * The envelope + byte-budget half of {@link pageListToolResult}, for a tool
+ * that paged EARLIER (e.g. it paged summary rows, then fetched bodies for
+ * just that page) and must not re-page — re-paging an already-paged set
+ * would report `next_cursor: null` because the set fits in one page.
+ */
+export function finishPagedListToolResult(toolName, { rows, next_cursor, limit }, { keyOf, idOf, extra = {} }) {
+  const spec = LIST_SPEC_TOOLS[toolName];
+  if (!spec) throw new Error(`finishPagedListToolResult: "${toolName}" is not in LIST_SPEC_TOOLS`);
+  const result = {
+    [spec.rows_key]: rows,
+    next_cursor: next_cursor ?? null,
+    page: { limit, returned: rows.length, byte_budget: spec.byte_budget, budget_trimmed: false },
+    ...extra,
+  };
+  const cursorFor = (row) => encodeListCursor({ k: keyOf(row), id: idOf(row) });
+  return fitPageToByteBudget(result, { rows_key: spec.rows_key, byte_budget: spec.byte_budget, cursorFor });
+}
+
+/**
+ * Follow `GET /api/specs` pages to exhaustion for an INTERNAL scan that
+ * genuinely needs every row of a projection (today: the on-deck amendment
+ * scan over `fields=amends,basename,type`). The console route now always
+ * answers a bounded page ([[HS-C6FO-8KK5-TASK-keyset-spec-list-endpoint-query-layer]]),
+ * so a caller that reads `body.specs` once silently sees only the first 100
+ * rows. This walks `next_cursor` at the route's max page size; `maxPages`
+ * bounds the walk so a cursor that never terminates cannot loop forever.
+ *
+ * Not for tool output — a tool that lists specs pages to the CALLER instead.
+ */
+export async function walkSpecListPages(consoleFetch, path, { limit = 500, maxPages = 200 } = {}) {
+  const rows = [];
+  let after = null;
+  for (let i = 0; i < maxPages; i += 1) {
+    const url = new URL(path, 'http://console.invalid');
+    url.searchParams.set('limit', String(limit));
+    if (after) url.searchParams.set('after', after);
+    const pagePath = `${url.pathname}${url.search}`;
+    const res = await consoleFetch(pagePath);
+    if (!res.ok) {
+      throw new Error(`GET ${pagePath} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`);
+    }
+    const specs = Array.isArray(res.body?.specs) ? res.body.specs : [];
+    rows.push(...specs);
+    const next = typeof res.body?.next_cursor === 'string' && res.body.next_cursor ? res.body.next_cursor : null;
+    if (!next || next === after || specs.length === 0) break;
+    after = next;
+  }
+  return rows;
+}

package/vendor/heyspex-mcp/login-handoff.mjs

@@ -96,7 +96,10 @@ export function statesMatch(received, expected) {
  *
  *   <consoleUrl>/companion/connect?port=<port>&state=<nonce>&client=cli[&label=<text>]
  */
-export function buildConnectUrl({ consoleUrl, port, state, client = LOGIN_CLIENT, label } = {}) {
+export function buildConnectUrl({ consoleUrl, port, state, client = LOGIN_CLIENT, label, prompt } = {}) {
+  if (prompt !== undefined && prompt !== null && !LOGIN_PROMPTS.includes(prompt)) {
+    throw new Error(`buildConnectUrl: prompt must be one of ${LOGIN_PROMPTS.join(', ')}`);
+  }
   if (typeof consoleUrl !== 'string' || !consoleUrl.trim()) {
     throw new Error('buildConnectUrl: consoleUrl is required');
   }
@@ -116,9 +119,20 @@ export function buildConnectUrl({ consoleUrl, port, state, client = LOGIN_CLIENT
   url.searchParams.set('state', state);
   url.searchParams.set('client', client || LOGIN_CLIENT);
   if (typeof label === 'string' && label.trim()) url.searchParams.set('label', label.trim());
+  if (prompt) url.searchParams.set('prompt', prompt);
   return url.toString();
 }
 
+/**
+ * `prompt=` values the console's /companion/connect page understands
+ * (spex-console/src/app/companion/connect/connect-flow.ts `CONNECT_PROMPTS`).
+ * With a prompt the page stops minting silently and asks "Signed in as X —
+ * continue / use a different account / create a new account" first
+ * ([[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]]). Same names
+ * as OpenID Connect's `prompt` parameter.
+ */
+export const LOGIN_PROMPTS = Object.freeze(['select_account', 'create']);
+
 /**
  * Reasons arrive from a browser redirect, i.e. from outside this process.
  * Clamp them to a short opaque token before they reach a terminal, a log, or

package/vendor/heyspex-mcp/mcp-config.mjs

@@ -0,0 +1,94 @@
+// Resolved MCP config: vault root, console URL, agent identity. Extracted from
+// cli.mjs under [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]]
+// (no behavior change).
+
+import { contextConsoleUrl } from './request-context.mjs';
+import { getActiveConfig } from './vault-resolve.mjs';
+import { resolveConsoleUrl } from '../../scripts/lib/console-url-resolver.mjs';
+
+export function getConfig() {
+  // Vault resolution is delegated to the shared 5-tier resolver
+  // (vault-resolve.mjs) so the MCP face agrees with the console face on which
+  // vault is active ([[HS-ICDI-TASK]] / [[HS-PNH2-RES]]). vaultRoot stays the
+  // repo root — every downstream call site joins `specs/` off it. Backward
+  // compatible: with only HEYSPEX_VAULT_ROOT set and no registry, the resolver
+  // returns that same repo root (tier 3).
+  // vaultId + vaultSource ([[HS-M95C]]): the locally resolved identity, so a
+  // cloud console request can be scoped to THIS repo's vault instead of the
+  // account's active-vault pointer (see console-fetch.mjs `getVaultIdHeader`).
+  const { repoRootAbs, vaultId, source: vaultSource } = getActiveConfig();
+  const vaultRoot = repoRootAbs;
+
+  const defaultRoadmapId = process.env.HEYSPEX_ROADMAP_ID || 'HS-ROADMAP-PRODUCT';
+
+  return { vaultRoot, vaultId, vaultSource, defaultRoadmapId };
+}
+
+// Resolved on every call (no caching): the MCP process is spawned once at
+// session start, but the console dev server may restart on a different port
+// later. Delegates to the ONE shared resolver
+// (scripts/lib/console-url-resolver.mjs, [[HS-GD45-MCPC-TASK]]) — MODE-AWARE
+// precedence ([[HS-VOJ7-YL1C-DIAG-console-url-resolver-ignores-dev-mode]]):
+// HEYSPEX_CONSOLE_URL env → ~/.heyspex/credentials.yaml `console_url` (written
+// by `hs mcp pair` / `hs login` / `hs dev mode:<...>`) → `.heyspex/console-url`
+// discovery file (written by `npm run dev`, see
+// `spex-console/scripts/ensure-next-dev.mjs`) but ONLY in local reliance →
+// the console URL derived from the resolved dev mode (prod / dev+cloud →
+// https://app.heyspex.com, dev+local → http://localhost:3000).
+export function getConsoleUrl() {
+  const { vaultRoot } = getConfig();
+  return resolveConsoleUrl({ repoRoot: vaultRoot });
+}
+
+/**
+ * The console origin THIS call actually talks to.
+ *
+ * `getConsoleUrl()` answers the PROCESS-wide question (env → credentials →
+ * discovery file → dev-mode default), which is the right answer for the stdio
+ * server. The console's remote endpoint (`POST /api/mcp`) runs the same
+ * handlers in-process and binds the deployment's OWN origin to the async call
+ * chain (request-context.mjs), so there `getConsoleUrl()` names a host the
+ * request never contacted — which is how a failure got reported "against
+ * console https://app.heyspex.com" when the fetch had gone to `selfOrigin()`.
+ * Every diagnostic that NAMES the console (error labels, `attempted`
+ * payloads, tier reports) must use this, not `getConsoleUrl()`, so the URL in
+ * the message is the URL that was used.
+ */
+export function effectiveConsoleUrl() {
+  return contextConsoleUrl() ?? getConsoleUrl();
+}
+
+export function detectAgentIdentity(argAgent, argSession) {
+  const trimmedAgent = typeof argAgent === 'string' ? argAgent.trim() : '';
+  const trimmedSession = typeof argSession === 'string' ? argSession.trim() : '';
+  if (trimmedAgent && trimmedSession) {
+    return { agent: trimmedAgent, sessionId: trimmedSession };
+  }
+  const claudeSession =
+    (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || '').trim();
+  if (claudeSession) {
+    return {
+      agent: trimmedAgent || 'Claude Code',
+      sessionId: trimmedSession || claudeSession,
+    };
+  }
+  const cursorSession =
+    (process.env.CURSOR_TRACE_ID
+      || process.env.CURSOR_SESSION_ID
+      || process.env.COMPOSER_SESSION_ID
+      || '').trim();
+  if (cursorSession) {
+    return {
+      agent: trimmedAgent || 'Cursor',
+      sessionId: trimmedSession || cursorSession,
+    };
+  }
+  return {
+    agent: trimmedAgent || process.env.HEYSPEX_AGENT?.trim() || 'External agent',
+    sessionId:
+      trimmedSession
+      || process.env.HEYSPEX_SESSION_ID?.trim()
+      || process.env.HEYSPEX_AGENT_SESSION?.trim()
+      || 'local',
+  };
+}