slidemind 0.3.20 → 0.4.0

package/src/builders/gate-session.js

@@ -68,6 +68,208 @@ const WIRE = {
 // is tiny, but a debounce still keeps typing off the storage path entirely.
 const DRAFT_DEBOUNCE_MS = 300;
 
+// ---------- decisions on the wire ----------
+// A decision POST answers with one of a small set of outcomes, and the page
+// reacts to each differently: a busy deck keeps the answer and re-sends it, a
+// stopped workspace waits for the heartbeat, a newer version reloads, a 401 is a
+// sign-out. These used to collapse into "any 409 = round superseded" and "any
+// failure = alert()", which locked the composer for good and lost answers.
+// Both gates (standalone and embedded) read the same table.
+const DECISION_CODES = new Set([
+  "stale_subject",
+  "local_conflict", // the record moved under the page: a newer version, like stale_subject
+  "deck_busy",
+  "approval_in_progress", // another approval is being written: retried like deck_busy
+  "already_answered",
+  "validation_failed",
+  "unauthorized",
+]);
+// Refusals the runner re-sends by itself (same request, same operationId).
+const RETRY_CODES = new Set(["deck_busy", "approval_in_progress"]);
+const BUSY_RETRY_MS = 3000;
+const OFFLINE_RETRY_MS = 5000;
+
+// One id per decision ATTEMPT, reused on every retry of it: the server answers a
+// repeated id idempotently, so a retry after a lost response can never answer
+// twice.
+export function newOperationId() {
+  try {
+    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === "function") return globalThis.crypto.randomUUID();
+  } catch {
+    /* fall through to the hand-rolled v4 */
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (ch) {
+    const r = (Math.random() * 16) | 0;
+    return (ch === "x" ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}
+
+// `status` + parsed body → { ok: true, ack } | { ok: false, code, message, retryable, details, status }.
+// `body` may be null (no JSON); a network failure is classified by the caller as
+// { ok:false, code:"offline" }. The standalone gate answers a settled run with
+// `{ error: "round_settled" }` (a plain string): another window already decided.
+export function classifyDecision(status, body) {
+  if (status >= 200 && status < 300) return { ok: true, ack: body && typeof body === "object" ? body : {} };
+  const err = body && body.error;
+  const raw = err && typeof err === "object" ? err.code : typeof err === "string" ? err : null;
+  const out = {
+    ok: false,
+    status,
+    code: raw || null,
+    message: err && typeof err === "object" && typeof err.message === "string" ? err.message : "",
+    retryable: !!(err && typeof err === "object" && err.retryable),
+    details: err && typeof err === "object" && err.details ? err.details : null,
+  };
+  // Only an EXPLICIT already_answered (or the standalone gate's round_settled)
+  // means "answered elsewhere": any other 409 (operation_mismatch,
+  // outcome_unknown, unsupported_format, …) is a failure that keeps the drafts
+  // and shows the server's words — never a silent switch to "answered".
+  if (status === 401) out.code = "unauthorized";
+  else if (raw === "round_settled") out.code = "already_answered";
+  else if (DECISION_CODES.has(raw)) out.code = raw;
+  else if (status >= 500 || raw === "workspace_stopping" || raw === "stopping") out.code = "offline";
+  else if (status === 422) out.code = "validation_failed";
+  else out.code = raw || "failed";
+  return out;
+}
+
+// One heartbeat answer → the connection state + the beat. A foreign service on
+// the port (or a non-JSON body) is NOT the workspace answering: it reads as
+// offline, never as "the agent stopped listening".
+export function readBeat(status, body, service) {
+  if (status === 401) return { conn: "signedout", beat: null };
+  if (!(status >= 200 && status < 300) || !body || typeof body !== "object") return { conn: "offline", beat: null };
+  if (service && body.service && body.service !== service) return { conn: "offline", beat: null };
+  return { conn: "online", beat: body };
+}
+
+// When the agent received the answer to `taskId`, or null.
+export function pickedUpAt(beat, taskId) {
+  const a = beat && beat.answered;
+  if (!a || !taskId || a.taskId !== taskId) return null;
+  return a.pickedUpAt || null;
+}
+
+// The decision state machine: one attempt at a time; a busy deck re-sends the
+// SAME request every 3 s, a stopped workspace re-sends it on `retryNow()` (the
+// heartbeat came back) or every 5 s, everything else ends the attempt.
+// `handlers`: onSuccess(ack) · onBusy({ since, elapsedMs, details }) ·
+// onOffline(outcome) · onFailed(outcome). `retryOffline: false` (the standalone
+// gate — its server is the command, and it does not come back) ends an offline
+// attempt as a failure instead of waiting.
+export function createDecisionRunner(opts) {
+  const doFetch = opts.fetch;
+  const endpoint = opts.endpoint;
+  // Wrapped, never stored bare: a browser's setTimeout called as a method of
+  // another object throws "Illegal invocation".
+  const timers = opts.timers || {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (id) => clearTimeout(id),
+  };
+  const now = opts.now || Date.now;
+  const busyMs = opts.busyRetryMs || BUSY_RETRY_MS;
+  const offlineMs = opts.offlineRetryMs || OFFLINE_RETRY_MS;
+  const retryOffline = opts.retryOffline !== false;
+  let current = null;
+
+  function finish(c) {
+    if (c.timer) timers.clearTimeout(c.timer);
+    c.timer = null;
+    if (current === c) current = null;
+  }
+  function schedule(c, ms) {
+    if (c.timer) timers.clearTimeout(c.timer);
+    c.timer = timers.setTimeout(function () {
+      c.timer = null;
+      send(c);
+    }, ms);
+  }
+  function send(c) {
+    if (current !== c || c.inFlight) return;
+    c.inFlight = true;
+    c.state = "sending";
+    let p;
+    try {
+      p = doFetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        credentials: "same-origin",
+        body: JSON.stringify(c.attempt.body),
+      });
+    } catch (e) {
+      p = Promise.reject(e);
+    }
+    Promise.resolve(p)
+      .then(
+        function (res) {
+          return Promise.resolve(res.json ? res.json() : null)
+            .catch(function () {
+              return null;
+            })
+            .then(function (body) {
+              return classifyDecision(res.status, body);
+            });
+        },
+        function () {
+          return { ok: false, code: "offline", status: 0, message: "", retryable: true, details: null, network: true };
+        },
+      )
+      .then(function (o) {
+        c.inFlight = false;
+        handle(c, o);
+      });
+  }
+  function handle(c, o) {
+    if (current !== c) return; // cancelled meanwhile
+    if (o.ok) {
+      finish(c);
+      c.handlers.onSuccess(o.ack);
+      return;
+    }
+    if (RETRY_CODES.has(o.code)) {
+      if (!c.busySince) c.busySince = now();
+      c.state = "busy";
+      c.handlers.onBusy({ since: c.busySince, elapsedMs: now() - c.busySince, details: o.details });
+      schedule(c, busyMs);
+      return;
+    }
+    if (o.code === "offline" && retryOffline) {
+      c.state = "offline";
+      c.handlers.onOffline(o);
+      schedule(c, offlineMs);
+      return;
+    }
+    finish(c);
+    c.handlers.onFailed(o);
+  }
+  return {
+    start(attempt, handlers) {
+      if (current) return false;
+      current = { attempt: attempt, handlers: handlers, timer: null, busySince: null, state: "sending", inFlight: false };
+      send(current);
+      return true;
+    },
+    // The heartbeat answered again: re-send a waiting attempt right away.
+    retryNow() {
+      const c = current;
+      if (!c || c.inFlight || (c.state !== "offline" && c.state !== "busy")) return false;
+      if (c.timer) timers.clearTimeout(c.timer);
+      c.timer = null;
+      send(c);
+      return true;
+    },
+    cancel() {
+      if (current) finish(current);
+    },
+    pending() {
+      return current ? current.attempt : null;
+    },
+    state() {
+      return current ? current.state : null;
+    },
+  };
+}
+
 export function createGateSession(cfg) {
   const name = cfg.name; // "review" | "plan" — storage prefix + wire shape
   const deck = cfg.deck || "";
@@ -79,9 +281,24 @@ export function createGateSession(cfg) {
   // would differ by definition).
   const LEDGER_KEY = "slidemind-" + name + "-ledger:" + deck;
   const CTX_KEY = "slidemind-" + name + "-ctx:" + deck;
-  const ROUND_READY_FLAG = "slidemind-" + name + "-round-ready";
+  // Per deck as well: the workspace page frames several decks' gates in ONE tab,
+  // and a tab's sessionStorage is shared by all of them.
+  const ROUND_READY_FLAG = "slidemind-" + name + "-round-ready:" + deck;
+  // A one-line message the NEXT load shows ("here is the new version, your
+  // comments are kept") — the reload that makes it true wipes the JS context.
+  const NOTICE_KEY = "slidemind-" + name + "-notice:" + deck;
   let draftTimer = null;
   let pollTimer = null;
+  // The decision wire. Embedded, a stopped workspace comes back (the daemon
+  // restarts), so an offline attempt waits for it; the standalone gate's server
+  // IS the command, so an offline attempt there ends.
+  const runner = createDecisionRunner({
+    fetch: doFetch,
+    endpoint: cfg.endpoint,
+    timers: cfg.timers,
+    now: cfg.now,
+    retryOffline: !!cfg.embedded,
+  });
 
   function read(key, fallback) {
     try {
@@ -110,21 +327,25 @@ export function createGateSession(cfg) {
       clearTimeout(draftTimer);
       draftTimer = null;
     }
-    write(CTX_KEY, Object.assign({ nonce: cfg.round || "" }, extra || {}));
+    write(CTX_KEY, Object.assign({ nonce: cfg.round || "", subject: cfg.subject || null }, extra || {}));
   }
   // Same write, coalesced — for the per-keystroke callers.
   function saveCtxSoon(extra) {
     if (draftTimer) clearTimeout(draftTimer);
     draftTimer = setTimeout(function () {
       draftTimer = null;
-      write(CTX_KEY, Object.assign({ nonce: cfg.round || "" }, extra || {}));
+      write(CTX_KEY, Object.assign({ nonce: cfg.round || "", subject: cfg.subject || null }, extra || {}));
     }, DRAFT_DEBOUNCE_MS);
   }
 
   // Restore this tab's session and work out whether THIS load is a new round.
   // Returns the ledger plus the round state; the caller applies its own ctx
   // fields from the returned `ctx` and its own round-arrival cosmetics.
-  function restore(seed) {
+  // `opts.hold(ctx)` may keep a changed nonce from counting as a new round: in
+  // the workspace the agent's edits change the content (and so the nonce) while
+  // it is still revising, and that is not the next round — the agent has not
+  // asked yet, so nothing it was handed is "addressed".
+  function restore(seed, opts) {
     let ledger = read(LEDGER_KEY, []) || [];
     if (!Array.isArray(ledger)) ledger = [];
     // A tab left open across the upgrade from the queueing release still holds
@@ -138,15 +359,26 @@ export function createGateSession(cfg) {
     let roundNo = ctx && typeof ctx.round === "number" ? ctx.round : 1;
     // A different SERVER nonce = a genuinely newer run served this page, i.e. a
     // new round. Same nonce = a plain refresh of the round already on screen.
-    const newRound = !!(ctx && ctx.nonce && cfg.round && ctx.nonce !== cfg.round);
+    const nonceMoved = !!(ctx && ctx.nonce && cfg.round && ctx.nonce !== cfg.round);
+    const held = nonceMoved && !!(opts && typeof opts.hold === "function" && opts.hold(ctx));
+    const newRound = nonceMoved && !held;
+    // The agent asked again on BYTE-IDENTICAL content (it read the comments and
+    // changed nothing): a new round, but nothing was worked in — the comments it
+    // was handed stay "sent", and the page must not say "updated".
+    const unchanged = newRound && !!(ctx && ctx.subject && cfg.subject && ctx.subject === cfg.subject);
+    const hadSent = ledger.some(function (c) {
+      return c.status === "sent";
+    });
     if (newRound) {
       roundNo += 1;
-      ledger.forEach(function (c) {
-        if (c.status === "sent") {
-          c.status = "addressed";
-          c.addressedInRound = roundNo;
-        }
-      });
+      if (!unchanged) {
+        ledger.forEach(function (c) {
+          if (c.status === "sent") {
+            c.status = "addressed";
+            c.addressedInRound = roundNo;
+          }
+        });
+      }
     }
     // Seed a tab with no session of its own (a fresh window) from the deck's
     // persisted round. These are the rows the agent has JUST been handed — they
@@ -165,7 +397,22 @@ export function createGateSession(cfg) {
     // sent this round; approving the same render again would only 409), and
     // ends the moment a newer run serves the page.
     const working = !newRound && !!(ctx && ctx.working);
-    return { ledger, roundNo, working, newRound, ctx };
+    return { ledger, roundNo, working, newRound, held, unchanged, hadSent, ctx };
+  }
+
+  // The one-line message for the next load (see NOTICE_KEY): written right
+  // before a reload, consumed once at boot.
+  function noteForNextLoad(note) {
+    write(NOTICE_KEY, note);
+  }
+  function consumeNote() {
+    const note = read(NOTICE_KEY, null);
+    try {
+      store.removeItem(NOTICE_KEY);
+    } catch {
+      /* storage blocked — nothing was stored either */
+    }
+    return note && typeof note === "object" ? note : null;
   }
 
   // Where a row stands, for the ledger rail / sidebar chip.
@@ -265,6 +512,9 @@ export function createGateSession(cfg) {
   // a tab buried in a background window must not swallow the round invisibly,
   // so the server opens a fresh browser tab and answers `action: "close"` here,
   // which retires this tab rather than reloading it into a hidden duplicate.
+  // STANDALONE gates only: inside the workspace page the shell's heartbeat
+  // monitor watches the round for the page's whole life (it never times out —
+  // the workspace page has no "session ended").
   function startNextRoundPolling(handlers) {
     if (pollTimer) return; // one poll per page life (working mode can re-enter)
     const startedAt = Date.now();
@@ -331,5 +581,16 @@ export function createGateSession(cfg) {
     consumeRoundFlag,
     announceNewRound,
     startNextRoundPolling,
+    noteForNextLoad,
+    consumeNote,
+    // the decision wire (see createDecisionRunner)
+    decide: runner.start,
+    retryDecision: runner.retryNow,
+    cancelDecision: runner.cancel,
+    decisionPending: runner.pending,
+    decisionState: runner.state,
+    newOperationId,
+    readBeat,
+    pickedUpAt,
   };
 }