heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/read-path.mjs

@@ -46,16 +46,19 @@
  * import) so tests can stub scripts/lib/dev-mode.mjs and prove the verdict
  * comes from `resolveDevMode` itself, not from string-matching this file.
  */
-import { dirname, join } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getActiveConfig } from './vault-resolve.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { importDevModeCore } from './dev-mode-core.mjs';
 // THIS PACKAGE's own root (vendor/heyspex-mcp/read-path.mjs -> two levels
 // up) — repo root in the monorepo, `node_modules/heyspex` in a packed
 // install. Used to locate this package's OWN sibling code (dev-mode.mjs);
-// see the module doc above for why this is never the vault root.
-const PACKAGE_ROOT = join(__dirname, '..', '..');
+// see the module doc above for why this is never the vault root. Derived in
+// ONE place (package-root.mjs) so a bundler bakes one build-machine path
+// into the console's remote-MCP chunk instead of one per module.
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { getActiveConfig } from './vault-resolve.mjs';
 
 /**
  * Resolve the VAULT root via the same shared 5-tier resolver every other MCP
@@ -78,8 +81,11 @@ export function resolveVaultRoot() {
 
 /** Real loader: dynamic-imports the shared dev-mode core from THIS PACKAGE's own root. */
 export async function loadRealDevMode() {
-  const coreUrl = pathToFileURL(join(PACKAGE_ROOT, 'scripts', 'lib', 'dev-mode.mjs')).href;
-  return import(coreUrl);
+  // Path candidate first (stdio / packed installs), then the static
+  // specifier a bundler can trace — see dev-mode-core.mjs. In a bundled
+  // deployment `import.meta.url` no longer points at a real checkout, so the
+  // path-built URL misses and the fallback is what actually loads.
+  return importDevModeCore([join(PACKAGE_ROOT, 'scripts', 'lib', 'dev-mode.mjs')]);
 }
 
 /**
@@ -94,6 +100,27 @@ export class ConsoleUnreachableCloudModeError extends Error {
   }
 }
 
+/**
+ * `{ degraded:true, source:'cloud', warning }` when the resolved vault is a
+ * satellite binding whose vault clone is absent on this machine (marker with
+ * vault_path, no clone), else null. Same record shape as the outage fallback.
+ */
+export function vaultNotClonedInfo() {
+  try {
+    const cfg = getActiveConfig();
+    if (cfg && cfg.vaultCloned === false) {
+      return {
+        degraded: true,
+        source: 'cloud',
+        warning: `vault ${cfg.vaultId} is bound by this repo's heyspex.yaml but is not cloned at ${cfg.vaultPath ?? 'its vault_path'} on this machine; answered from the cloud (cloud-only mode). Clone the vault repo there for local reads.`,
+      };
+    }
+  } catch {
+    /* resolver failure: not a clone problem */
+  }
+  return null;
+}
+
 /**
  * resolveReadTier({ env, homeDir, loadDevMode? }) -> "disk" | "neon"
  *
@@ -112,23 +139,172 @@ export async function resolveReadTier({ env, homeDir, loadDevMode = loadRealDevM
 }
 
 /**
- * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl })
+ * resolveVaultWriteMode({ env, homeDir, loadDevMode? }) -> "local" | "cloud"
+ *
+ * The write-side twin of {@link resolveReadTier}: whatever
+ * `resolveDevMode(...).vaultWriteMode` says — `local` only for dev mode with
+ * local reliance, `cloud` for prod and for dev with cloud reliance. A
+ * create-flow that writes the vault directly (save_research) consults THIS
+ * before touching disk, so a cloud-reliant session never leaves a file the
+ * console's index has never heard of (the split-brain a disk write in cloud
+ * mode produces). Same injectable loader as the read tier.
+ */
+export async function resolveVaultWriteMode({ env, homeDir, loadDevMode = loadRealDevMode } = {}) {
+  const mod = await loadDevMode();
+  const resolved = mod.resolveDevMode({ env, homeDir });
+  return resolved.vaultWriteMode === 'local' ? 'local' : 'cloud';
+}
+
+/**
+ * A console read that failed, carrying the transport verdict so
+ * {@link readViaSelector} can tell an OUTAGE (status 0, 5xx, timeout/network)
+ * from an ANSWER (401/403/404/409). Thrown by the `neonRead` closures; build
+ * one from a consoleFetch result with {@link consoleReadErrorFrom}.
+ */
+export class ConsoleReadError extends Error {
+  constructor(message, { status, errorKind, route } = {}) {
+    super(message);
+    this.name = 'ConsoleReadError';
+    this.status = status;
+    this.errorKind = errorKind;
+    this.route = route;
+  }
+}
+
+/** Build a {@link ConsoleReadError} from a consoleFetch result `{status, errorKind}`. */
+export function consoleReadErrorFrom(res, message, route) {
+  const e = new ConsoleReadError(message, { status: res?.status, errorKind: res?.errorKind, route });
+  if (res?.authProblem || res?.refusal) e.authProblem = true;
+  return e;
+}
+
+/**
+ * True when `err` says the console was unreachable or broken (status 0, any
+ * 5xx, errorKind timeout/abort/network). False for answered 4xx verdicts
+ * (401/403/404/409) and for anything unclassified.
+ */
+export function isOutageClass(err) {
+  if (!err || typeof err !== 'object') return false;
+  if (err.authProblem) return false; // sign-in / scope refusals are not outages
+  const { status, errorKind } = err;
+  if (errorKind === 'timeout' || errorKind === 'abort' || errorKind === 'network') return true;
+  if (typeof status === 'number' && (status === 0 || status >= 500)) return true;
+  return false;
+}
+
+// Per-call collector so callers whose reader returns a non-object (Set, array,
+// null) can still learn that the answer came from the local clone.
+const degradationScope = new AsyncLocalStorage();
+
+/**
+ * Run `fn`, collecting a {@link readViaSelector} degradation record for every
+ * disk-fallback read made inside it. Resolves `{ value, degraded }` where
+ * `degraded` is null or `{ degraded:true, source:'disk', cloud_error, warning }`.
+ */
+export async function withDegradationScope(fn) {
+  const records = [];
+  const value = await degradationScope.run(records, fn);
+  return { value, degraded: records[0] ?? null };
+}
+
+function lastCommitIso(root) {
+  try {
+    const out = execFileSync('git', ['-C', root, 'log', '-1', '--format=%cI'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000,
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stamp a degradation record onto a reader's result. Plain objects get the
+ * fields spread in; an MCP tool result (`{content:[{type:'text',text:<json>}]}`)
+ * gets them merged into the JSON payload inside `text` (and spread on the
+ * envelope too); any other shape (Set/array/null/primitive) is returned
+ * unchanged — it rides the {@link withDegradationScope} collector instead.
+ */
+export function mergeDegradation(result, info) {
+  if (!isPlainObject(result) || !info) return result;
+  const first = Array.isArray(result.content) ? result.content[0] : null;
+  if (first && first.type === 'text' && typeof first.text === 'string') {
+    try {
+      const parsed = JSON.parse(first.text);
+      if (isPlainObject(parsed)) {
+        return { ...result, ...info, content: [{ ...first, text: JSON.stringify({ ...parsed, ...info }, null, 2) }, ...result.content.slice(1)] };
+      }
+    } catch {
+      /* not JSON — fall through to the envelope spread */
+    }
+  }
+  return { ...result, ...info };
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+
+/**
+ * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl, vaultRoot?, allowDiskFallback? })
  *
  * Runs the read matching `tier`:
  *   - "disk": calls `diskRead()` (`neonRead` is never invoked).
- *   - "neon": calls `neonRead()`. On failure, wraps the error into a plain
- *     {@link ConsoleUnreachableCloudModeError} naming `consoleUrl` and
- *     `routeLabel`; `diskRead` is never called (no silent local fallback
- *     out of cloud reliance).
+ *   - "neon": calls `neonRead()`. On failure:
+ *       * DEGRADE ("degrade, don't die"): when `diskRead` exists, the failure
+ *         is outage-class ({@link isOutageClass}), a local clone exists
+ *         (`<vaultRoot>/specs`), and HEYSPEX_NO_DISK_FALLBACK !== '1', answer
+ *         from `diskRead()`. A plain-object result is returned spread with
+ *         `degraded: true, source: 'disk', cloud_error, warning`; any other
+ *         shape (Set/array/null) is returned unchanged and the same record is
+ *         pushed to the active {@link withDegradationScope} collector.
+ *       * otherwise wraps the error into {@link ConsoleUnreachableCloudModeError}
+ *         naming `consoleUrl` and `routeLabel` (4xx, no clone, no diskRead,
+ *         opt-out env, or `allowDiskFallback: false` for write preconditions).
  */
-export async function readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl }) {
+export async function readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl, vaultRoot, allowDiskFallback = true }) {
+  // A satellite whose marker names a vault that is not cloned here is
+  // CLOUD-ONLY: a disk read would silently answer empty. Serve the cloud read
+  // (when this read has one) and declare it - never a silent empty answer.
+  const uncloned = vaultNotClonedInfo();
+  if (uncloned && typeof neonRead === 'function') {
+    const result = await neonRead();
+    const store = degradationScope.getStore();
+    if (store) store.push(uncloned);
+    return mergeDegradation(result, uncloned);
+  }
   if (tier === 'disk') {
+    if (uncloned) {
+      throw new ConsoleUnreachableCloudModeError(
+        `VAULT_NOT_CLONED_LOCALLY: route "${routeLabel}" has no cloud read and ${uncloned.warning}`,
+      );
+    }
     return diskRead();
   }
   if (tier === 'neon') {
     try {
       return await neonRead();
     } catch (err) {
+      const root = vaultRoot ?? resolveVaultRoot();
+      if (
+        allowDiskFallback &&
+        typeof diskRead === 'function' &&
+        isOutageClass(err) &&
+        process.env.HEYSPEX_NO_DISK_FALLBACK !== '1' &&
+        root && existsSync(join(root, 'specs'))
+      ) {
+        const result = await diskRead();
+        const kind = err.status ? `HTTP ${err.status}` : (err.errorKind ?? 'unreachable');
+        const info = {
+          degraded: true,
+          source: 'disk',
+          cloud_error: String(err?.message ?? err),
+          warning: `Console ${consoleUrl} failed (${kind}); answered from the local clone at ${root} (last commit ${lastCommitIso(root)}). Writes still require the console.`,
+        };
+        const store = degradationScope.getStore();
+        if (store) store.push(info);
+        return mergeDegradation(result, info);
+      }
       throw new ConsoleUnreachableCloudModeError(
         `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl} — ${String(err?.message ?? err)}`,
       );

package/vendor/heyspex-mcp/receipt-shape.mjs

@@ -0,0 +1,146 @@
+// The read-back receipt envelope for `hs` verbs that live in plain .mjs under
+// vendor/heyspex-mcp/ and so cannot import the TypeScript receipt
+// (spex-console/src/lib/cli/receipt.ts, [[HS-STCY-WW9R-TASK-add-a-shared-receipt-that-reads-back]]).
+// Same envelope, same words: `{ local, cloud, verified, agree, diffs, changed,
+// failed?, retry? }`, a two-column "local (this machine) | cloud (console)"
+// table and one "Result:" line with the same anchors (verified / unverified /
+// disagree / failed). Only the side fields differ per verb, so a verb passes a
+// row table naming which local field and which cloud field each row shows
+// and whether the row must agree. `hs login` is the first user
+// ([[HS-CRNE-WW9R-TASK-give-hs-install-and-hs-login-the]], epic
+// [[HS-L6HW-WW9R-EPIC-one-http-transport-and-measured]] invariant 6).
+//
+// Pure: no IO, never throws.
+
+/** `EXIT.ACCOUNT_MISMATCH` in spex-console/src/lib/cli/control-shared.ts — the console confirmed another account. */
+export const EXIT_ACCOUNT_MISMATCH = 20;
+/** `EXIT.RECEIPT_DISAGREE` in control-shared.ts — both sides were read back and disagree. */
+export const EXIT_RECEIPT_DISAGREE = 21;
+
+/**
+ * @typedef {{ read: boolean, reason?: string, [field: string]: unknown }} ReceiptSide
+ * @typedef {{ label: string, local?: string, cloud?: string, compare?: boolean }} ReceiptRow
+ *   One table row: the local side's field, the cloud side's field, and
+ *   whether the two must be equal for `agree` (a diff is named by `label`).
+ */
+
+/** A side that was not read back, with the reason. */
+export function unreadSide(reason) {
+  return { read: false, reason };
+}
+
+const META = new Set(['read', 'reason']);
+
+function valueOf(side, field) {
+  if (!side || !field) return null;
+  const v = side[field];
+  return v === undefined ? null : v;
+}
+
+/**
+ * Build the receipt from the two read-backs.
+ *  - `verified`: both sides were read back;
+ *  - `diffs`: every `compare` row whose two values differ (only when verified);
+ *  - `agree`: verified with no diffs;
+ *  - `changed`: per side, every field that differs from the `before` read of
+ *    that side (`[]` on an unchanged re-run; a side with no before read, or
+ *    not read after, contributes nothing).
+ * @param {{ local: ReceiptSide | null, cloud: ReceiptSide | null, rows: ReceiptRow[],
+ *   before?: { local?: ReceiptSide | null, cloud?: ReceiptSide | null },
+ *   failed?: { side: 'local' | 'cloud', reason?: string }, retry?: string }} input
+ */
+export function buildSidesReceipt({ local, cloud, rows, before = {}, failed, retry }) {
+  const l = local ?? unreadSide('not read back');
+  const c = cloud ?? unreadSide('not read back');
+  if (failed?.reason) (failed.side === 'cloud' ? c : l).reason = failed.reason;
+  const verified = l.read === true && c.read === true;
+
+  const diffs = [];
+  if (verified) {
+    for (const row of rows) {
+      if (!row.compare) continue;
+      const lv = valueOf(l, row.local);
+      const cv = valueOf(c, row.cloud);
+      if (lv !== cv) diffs.push({ field: row.label, local: lv, cloud: cv });
+    }
+  }
+
+  const changed = [];
+  for (const [name, after] of [['local', l], ['cloud', c]]) {
+    const prior = before[name];
+    if (!prior?.read || !after.read) continue;
+    const fields = new Set([...Object.keys(prior), ...Object.keys(after)].filter((f) => !META.has(f)));
+    for (const field of fields) {
+      const from = valueOf(prior, field);
+      const to = valueOf(after, field);
+      if (from !== to) changed.push({ side: name, field, from, to });
+    }
+  }
+
+  return {
+    local: l,
+    cloud: c,
+    verified,
+    agree: verified && diffs.length === 0,
+    diffs,
+    changed,
+    ...(failed ? { failed: failed.side } : {}),
+    ...(retry ? { retry } : {}),
+  };
+}
+
+/** The one-word state a script or test can branch on (same as receipt.ts `receiptStatus`). */
+export function sidesReceiptStatus(receipt) {
+  if (receipt.failed) return 'failed';
+  if (!receipt.verified) return 'unverified';
+  if (!receipt.agree) return 'disagree';
+  return 'verified';
+}
+
+function cell(side, field) {
+  if (!field) return '';
+  if (!side.read) return '(not read)';
+  const v = valueOf(side, field);
+  if (v === null) return '(none)';
+  if (typeof v === 'boolean') return v ? 'yes' : 'no';
+  return String(v);
+}
+
+const show = (v) => (v === null || v === undefined ? '(none)' : String(v));
+
+/**
+ * The text sink: the same two-column table and "Result:" line as receipt.ts
+ * `formatReceipt`, rows taken from `rows`.
+ * @param {ReturnType<typeof buildSidesReceipt>} receipt
+ * @param {ReceiptRow[]} rows
+ */
+export function formatSidesReceipt(receipt, rows) {
+  const table = [
+    ['', 'local (this machine)', 'cloud (console)'],
+    ...rows.map((r) => [r.label, cell(receipt.local, r.local), cell(receipt.cloud, r.cloud)]),
+  ];
+  const w0 = Math.max(...table.map((r) => r[0].length));
+  const w1 = Math.max(...table.map((r) => r[1].length));
+  const lines = [
+    'Read back after the write:',
+    ...table.map(([a, b, c]) => `  ${a.padEnd(w0)}  ${b.padEnd(w1)}  ${c}`.trimEnd()),
+  ];
+  const status = sidesReceiptStatus(receipt);
+  const retry = receipt.retry ? ` Retry: \`${receipt.retry}\`` : '';
+  if (status === 'failed') {
+    const reason = receipt[receipt.failed].reason;
+    lines.push(`Result: failed -- the ${receipt.failed} half did not land${reason ? ` (${reason})` : ''}.${retry}`);
+  } else if (status === 'unverified') {
+    const unread = ['local', 'cloud'].filter((s) => !receipt[s].read);
+    const why = unread.map((s) => `${s}${receipt[s].reason ? `: ${receipt[s].reason}` : ''}`).join('; ');
+    lines.push(`Result: unverified -- the ${unread.join(' and ')} side was not read back (${why}).`);
+  } else if (status === 'disagree') {
+    lines.push(
+      `Result: the two sides disagree on ${receipt.diffs.map((d) => d.field).join(', ')}.${retry}`,
+      ...receipt.diffs.map((d) => `  ${d.field}: local ${show(d.local)} | cloud ${show(d.cloud)}`),
+    );
+  } else {
+    lines.push('Result: verified -- both sides were read back and agree.');
+  }
+  return lines.join('\n');
+}

package/vendor/heyspex-mcp/recipe-handlers.mjs

@@ -0,0 +1,117 @@
+// heyspex_start_recipe and heyspex_list_recipes handlers (recipe-tools.mjs holds the store). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { wrapDesignResult } from './tool-helpers.mjs';
+import { executeListRecipes, executeStartRecipe } from './recipe-tools.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { consoleErrorMessage } from './console-fetch.mjs';
+import { createCaptureSessionOnConsole, writeCaptureFocusVendor } from './capture-tools.mjs';
+
+// heyspex_list_recipes — pure catalog scan wrapped for the tool surface.
+export function handleListRecipes(vaultRoot, args) {
+  return wrapDesignResult(executeListRecipes(vaultRoot, args));
+}
+
+// heyspex_start_recipe — resolve the recipe (pure) then, when the console is
+// reachable, create + pin a capture session tied to it (mirrors
+// handlePinCapture). The recipe start context is returned in every case so the
+// flow can be walked even when the capture could not be created (offline).
+export async function handleStartRecipe(vaultRoot, args) {
+  const resolved = executeStartRecipe(vaultRoot, args);
+  if (resolved.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(resolved, null, 2) }],
+    };
+  }
+  const recipe = resolved.recipe;
+  const identity = detectAgentIdentity();
+
+  const createResult = await createCaptureSessionOnConsole({
+    opened_by: 'agent',
+    opened_by_session: identity.sessionId,
+    mode: 'attended',
+    status: 'pending',
+  });
+
+  if (createResult.ok && createResult.session) {
+    const session = createResult.session;
+    const pin = await writeCaptureFocusVendor(vaultRoot, {
+      specId: session.id,
+      specPath: session.specPath || '',
+      reason: `Started workflow-recipe ${recipe.recipe_id} (${recipe.name})`,
+      claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+    });
+    if (!pin.pinned) {
+      // The session row WAS created and the recipe context is intact — both are
+      // returned so nothing is lost and no second session gets minted. But the
+      // message may not say "pinned" over a pin that never persisted
+      // ([[HS-IOJW-5YDH-DIAG]] sweep: report the result, not the request).
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            started: true,
+            pinned: false,
+            error: 'CAPTURE_PIN_NOT_WRITTEN',
+            source: 'database',
+            capture: { spec_id: session.id, spec_path: session.specPath || null },
+            pin,
+            recipe,
+            message:
+              `Capture session ${session.id} was created for workflow-recipe ${recipe.recipe_id}, but the ` +
+              `capture-on-deck pin was NOT written (${pin.reason}). A later /hs-capture with no id will ` +
+              'resolve to a DIFFERENT capture. Do not re-run heyspex_start_recipe (it would mint a second ' +
+              `session) — re-pin with heyspex_pin_capture({ spec_id: "${session.id}" }) once the console is healthy.`,
+          }, null, 2),
+        }],
+      };
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          started: true,
+          pinned: true,
+          pin,
+          source: 'database',
+          capture: { spec_id: session.id, spec_path: session.specPath || null },
+          recipe,
+          message: `Capture session ${session.id} created and pinned (${pin.tier}) for workflow-recipe ${recipe.recipe_id}. Walk the capture_sequence, then file the spec pre-filled from spec_template (recipe_id + tool_scope stamp provenance).`,
+        }, null, 2),
+      }],
+    };
+  }
+
+  // The create failed → the recipe context is still fully returned so the flow
+  // can be walked / filed later. No divergent local capture file is minted
+  // (capture is online-only, [[heyspex-is-online-only-no-offline]]).
+  //
+  // HS-I6HT: this used to hardcode "HeySpex can't reach the server right now"
+  // for EVERY failure, so a sign-in failure printed an outage sentence next to
+  // a CONSOLE_NOT_SIGNED_IN code — two contradictory stories in one payload.
+  // `consoleErrorMessage` already writes the right sentence per class (sign-in,
+  // 401, wrong port, timeout, genuinely down); use it whenever it has one, and
+  // keep the old wording only as the last-resort fallback.
+  const answered =
+    typeof createResult.result?.body?.message === 'string'
+      ? createResult.result.body.message
+      : null;
+  const whatHappened =
+    (createResult.result ? consoleErrorMessage(createResult.result, answered) : null)
+    || "HeySpex can't reach the server right now.";
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        started: false,
+        status: 'deferred',
+        error: createResult.error || 'CONSOLE_UNREACHABLE',
+        recipe,
+        message:
+          `${whatHappened} The capture wasn't created, but the recipe's steps are returned below and nothing is lost. Fix the cause above, then call again to pin the capture.`,
+      }, null, 2),
+    }],
+  };
+}