heyspex 0.1.0

package/vendor/heyspex-mcp/capture-console-client.mjs

@@ -0,0 +1,290 @@
+/**
+ * Console capture-session client — extracted from cli.mjs so the error
+ * classification and outbox drain logic are unit-testable without starting
+ * the full MCP server (which begins reading stdin + spawns the
+ * capture-channel watcher on import).
+ *
+ * Owning epic: [[HS-EPIC-CPMR-capture-session-patch-materialized-rows-reliability]].
+ *
+ * Design: a factory `makeCaptureConsoleClient(consoleFetch)` returns a bound
+ * client. cli.mjs creates one at module load with its real `consoleFetch`;
+ * tests create one with a stub. No module-level side effects on import.
+ */
+
+import {
+  listOutbox,
+  outboxCount,
+  outboxEntryToPatch,
+  quarantineOutboxEntry,
+  removeOutboxEntry,
+  stashCaptureArgs,
+} from "./capture-outbox.mjs";
+
+/**
+ * Error taxonomy for capture-session console calls ([[HS-K27H-DIAG-0G86]]).
+ *
+ * - `CONSOLE_UNREACHABLE` (status === 0): genuine TRANSPORT failure —
+ *   ECONNREFUSED / DNS / timeout / abort (console-fetch stamps status 0 on
+ *   all of these; an HTTP response the server returned always has status > 0).
+ *   The ONLY class that touches the offline buffer: stash, the next drain
+ *   replays.
+ * - `CAPTURE_CONFLICT` (4xx): the server ANSWERED and structurally refused
+ *   (abandoned row, validation failure, malformed body). A client error that
+ *   will fail identically on retry. NEVER stash; surface the server's
+ *   error + message verbatim; quarantine on drain.
+ * - `PATCH_FAILED` (5xx or other): the server ANSWERED and errored applying
+ *   the write. NEVER stash — pre-K27H this was "stashed like UNREACHABLE",
+ *   which reported real server failures as connectivity blips with a false
+ *   "your words are saved and will sync" promise. Surface the server's
+ *   message verbatim. (Entries ALREADY in the outbox from a genuine
+ *   transport failure still pause the drain on 5xx and retry later — the
+ *   ban is on adding new entries for an answered request.)
+ */
+export const CAPTURE_ERROR_UNREACHABLE = "CONSOLE_UNREACHABLE";
+export const CAPTURE_ERROR_CONFLICT = "CAPTURE_CONFLICT";
+export const CAPTURE_ERROR_FAILED = "PATCH_FAILED";
+
+/** Classify a `consoleFetch` result by HTTP status range. */
+export function classifyConsoleFetchError(result) {
+  if (result.status === 0) return CAPTURE_ERROR_UNREACHABLE;
+  if (result.status >= 400 && result.status < 500)
+    return CAPTURE_ERROR_CONFLICT;
+  return CAPTURE_ERROR_FAILED;
+}
+
+/** Extract the console's error message from a failed `consoleFetch` result. */
+export function extractConsoleMessage(result) {
+  return result?.body?.message || result?.body?.error || null;
+}
+
+/**
+ * Classify a failed capture write and build the honest description of what
+ * happened ([[HS-K27H-DIAG-0G86]] AC1-AC5). Pure — no fs, no HTTP.
+ *
+ * Accepts either failure shape used on the capture surface:
+ *   - patchCaptureSession failures: `{ ok:false, error, status, consoleMessage, result }`
+ *   - list/create helper failures:  `{ ok:false, error, result }` (status on `result`)
+ *
+ * @returns {{
+ *   kind: 'transport'|'client'|'server',
+ *   shouldStash: boolean,
+ *   error: string,
+ *   http_status: number,
+ *   server_error_code: string|null,
+ *   server_message: string|null,
+ *   message: string|null,
+ * }}
+ */
+export function describeCaptureWriteFailure(failure) {
+  const result = failure?.result ?? failure ?? {};
+  const status =
+    typeof failure?.status === "number"
+      ? failure.status
+      : typeof result?.status === "number"
+        ? result.status
+        : 0;
+  const serverCode = typeof result?.body?.error === "string" ? result.body.error : null;
+  const serverMessage = typeof result?.body?.message === "string" ? result.body.message : null;
+
+  // status 0 ⇔ genuine transport failure (ECONNREFUSED / DNS / timeout /
+  // abort — console-fetch stamps status 0 on every non-response). Anything
+  // else is an HTTP response the server actually returned.
+  if (status === 0) {
+    return {
+      kind: "transport",
+      shouldStash: true,
+      error: failure?.error || CAPTURE_ERROR_UNREACHABLE,
+      http_status: 0,
+      server_error_code: null,
+      server_message: null,
+      message: null, // the responder composes the transport message (depends on what stashed)
+    };
+  }
+
+  const label = `HTTP ${status}${serverCode ? ` ${serverCode}` : ""}`;
+  const verbatim = serverMessage ? `: ${serverMessage}` : "";
+  if (status >= 400 && status < 500) {
+    return {
+      kind: "client",
+      shouldStash: false,
+      error: CAPTURE_ERROR_CONFLICT,
+      http_status: status,
+      server_error_code: serverCode,
+      server_message: serverMessage,
+      message:
+        `The server rejected this write (${label})${verbatim}. ` +
+        `The console answered — it is not down. This write was NOT saved and will NOT retry automatically; fix the request and send it again.`,
+    };
+  }
+  return {
+    kind: "server",
+    shouldStash: false,
+    error: CAPTURE_ERROR_FAILED,
+    http_status: status,
+    server_error_code: serverCode,
+    server_message: serverMessage,
+    message:
+      `The server failed to apply this write (${label})${verbatim}. ` +
+      `The console answered — it is not down; the write errored server-side. This write was NOT saved and will NOT retry automatically; check the server logs and send it again.`,
+  };
+}
+
+/**
+ * Build the tool-facing payload for a failed capture write, performing the
+ * offline-buffer stash ONLY for genuine transport failures (AC1). This is the
+ * single buffering decision point for the capture write path — extracted here
+ * (rather than living in cli.mjs's handler) so the stash-vs-surface rule is
+ * unit-testable against a real tmp outbox.
+ *
+ * - transport → stash `args`' content fields; the "will sync automatically"
+ *   promise appears ONLY when something was actually written to the outbox
+ *   (AC4) — the drain path replays every OUTBOX_KINDS field in canonical
+ *   structured shape.
+ * - 4xx → `status: "refused"` + the server's error/message verbatim (AC2/AC5).
+ * - 5xx → `status: "failed"` + the server's message verbatim (AC3/AC5).
+ */
+export function respondToCaptureWriteFailure(vaultRoot, args, failure) {
+  const d = describeCaptureWriteFailure(failure);
+  if (d.kind === "transport") {
+    const stashed = stashCaptureArgs(vaultRoot, args || {});
+    const pending = outboxCount(vaultRoot);
+    return {
+      ok: false,
+      status: "deferred",
+      error: d.error,
+      source: "offline-buffer",
+      message:
+        stashed.length > 0
+          ? "HeySpex can't reach the server right now, so this capture isn't filed yet — but your exact words are saved to the offline buffer and will sync automatically on the next capture call once the connection is back. Nothing is lost."
+          : "HeySpex can't reach the server right now. Anything you've already captured is safe — please try again in a moment.",
+      stashed: stashed.map((s) => ({ kind: s.kind })),
+      pending_sync: pending,
+    };
+  }
+  return {
+    ok: false,
+    status: d.kind === "client" ? "refused" : "failed",
+    error: d.error,
+    http_status: d.http_status,
+    server_error: d.server_error_code,
+    // Back-compat key (tool description documents `console_error` as the
+    // verbatim server message).
+    console_error: d.server_message ?? d.server_error_code,
+    buffered: false,
+    message: d.message,
+  };
+}
+
+/**
+ * @typedef {object} ConsoleFetchResult
+ * @property {boolean} ok
+ * @property {number} status
+ * @property {*} body
+ * @property {string} [url]
+ * @property {string} [error]
+ *
+ * @callback ConsoleFetchFn
+ * @param {string} path
+ * @param {object} [options]
+ * @returns {Promise<ConsoleFetchResult>}
+ */
+
+/**
+ * Build a capture-session console client bound to a `consoleFetch` function.
+ *
+ * @param {ConsoleFetchFn} consoleFetch
+ */
+export function makeCaptureConsoleClient(consoleFetch) {
+  /**
+   * PATCH a capture session's content_buffer or attach an agent.
+   *
+   * Returns:
+   *   - on success: `{ ok: true, session, materialization, result }`
+   *   - on failure: `{ ok: false, error: <code>, status, consoleMessage, result }`
+   *     where `error` is one of CAPTURE_ERROR_*.
+   */
+  async function patchCaptureSession(sessionId, patchBody) {
+    const result = await consoleFetch(
+      `/api/capture/sessions/${encodeURIComponent(sessionId)}`,
+      { method: "PATCH", body: patchBody },
+    );
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: classifyConsoleFetchError(result),
+        status: result.status,
+        consoleMessage: extractConsoleMessage(result),
+        result,
+      };
+    }
+    return {
+      ok: true,
+      session: result.body?.session,
+      materialization: result.body?.materialization,
+      result,
+    };
+  }
+
+  /**
+   * Drain offline-buffered captures into the now-reachable session, oldest first.
+   *
+   * Per [[HS-EPIC-CPMR]]:
+   *   - `CAPTURE_CONFLICT` (4xx): quarantine + KEEP DRAINING. Pre-fix this
+   *     would head-of-line-block the queue forever (the offline buffer was the
+   *     dead-letter graveyard for misclassified materialized-row 409s).
+   *   - `CONSOLE_UNREACHABLE` / `PATCH_FAILED` (5xx): break — leave the rest
+   *     for the next reachable call.
+   *
+   * @param {object} [currentBuffer] - the session's current content_buffer,
+   *   threaded through `outboxEntryToPatch` so append-shaped sections
+   *   (userQuotes/chatTurns) merge with what is already on the session
+   *   instead of clobbering it; updated locally as entries drain so
+   *   multiple stashed quotes accumulate ([[HS-K27H-DIAG-0G86]] AC4 —
+   *   replay must be genuinely lossless for the sync promise to be honest).
+   * @returns {Promise<{drained: number, quarantined: number, remaining: number}>}
+   */
+  async function drainOutbox(vaultRoot, sessionId, identity, currentBuffer = {}) {
+    const pending = listOutbox(vaultRoot);
+    if (pending.length === 0) {
+      return { drained: 0, quarantined: 0, remaining: 0 };
+    }
+    let drained = 0;
+    let quarantined = 0;
+    let localBuffer =
+      currentBuffer && typeof currentBuffer === "object" ? currentBuffer : {};
+    for (const entry of pending) {
+      const patch = outboxEntryToPatch(entry, new Date().toISOString(), localBuffer);
+      if (!patch) {
+        removeOutboxEntry(entry.path); // unmappable — discard so it can't wedge the queue
+        continue;
+      }
+      const res = await patchCaptureSession(sessionId, {
+        patches: [patch],
+        attach: { agent: identity.agent, sessionId: identity.sessionId },
+      });
+      if (res.ok) {
+        removeOutboxEntry(entry.path);
+        drained += 1;
+        // Mirror the server's last-write-wins merge locally so the NEXT
+        // entry's append-shaped patch builds on this one.
+        localBuffer = { ...localBuffer, [patch.path]: patch.value };
+        continue;
+      }
+      if (res.error === CAPTURE_ERROR_CONFLICT) {
+        quarantineOutboxEntry(vaultRoot, entry.path, {
+          reason: "console_refused",
+          status: res.status,
+          consoleMessage: res.consoleMessage,
+        });
+        quarantined += 1;
+        continue;
+      }
+      // Transient (unreachable / 5xx) — leave remainder for next call.
+      // Do not drain any more entries after encountering a transient error
+      break;
+    }
+    return { drained, quarantined, remaining: outboxCount(vaultRoot) };
+  }
+
+  return { patchCaptureSession, drainOutbox };
+}