@panphora/clayjs 0.4.3 → 0.6.0

package/src/plugins/wire.js

@@ -0,0 +1,598 @@
+import { isEditMode } from "../core/is-edit-mode.js";
+
+/**
+ * clay.wire — a per-file control channel between this page and a local process.
+ *
+ * The page sends a request ("rewrite the section I circled"), a process running
+ * in the user's own terminal answers with progress and a terminal frame, and
+ * that process edits the FILE. HTML never rides the wire: the agent's change
+ * reaches this page as an ordinary external file change, through live-sync. That
+ * split is why this module has no morphing, no content lane, and no opinion
+ * about what a payload contains.
+ *
+ * Three constraints shape everything below.
+ *
+ * It must not import the sync plugin. `sync/live-sync.js` opens an EventSource
+ * on evaluation, so a static import here would give every wire page a live-sync
+ * connection it never asked for. The one thing this module needs from live-sync,
+ * "a disk frame just landed", arrives as the `clay:sync-applied` DOM event, which
+ * couples the two through the document rather than through the module graph.
+ *
+ * It runs in view mode (`editOnly: false` in the loader's plugin table), because
+ * the `/htmlfile questions` consumer and every read-only review page need it. So
+ * nothing here may assume the save lane exists: on a view-mode page `clay.save`
+ * is absent, and the save-protection below is skipped entirely rather than
+ * guarded at each call site.
+ *
+ * The stream is lazy. A browser allows six connections per origin, the pool is
+ * shared across tabs, and live-sync already holds one per tab, so a second
+ * permanent stream means three tabs of one project saturate the origin and the
+ * next save queues behind them. The wire is idle between requests by definition,
+ * so it connects on the first in-flight request and disconnects after the last
+ * one ends.
+ */
+
+// Every request carries a deadline, from before its POST until it ends. Nothing
+// else can end one: the wire has no "the handler detached" signal, and a handler
+// that acknowledged and then died would otherwise leave the request open, its
+// promise unresolved, and saving paused for the rest of the session. That is the
+// worst outcome available here, worse than reporting a slow agent as failed,
+// because the page silently stops saving.
+//
+// It runs on two lengths. Before the first frame, the handler has taken the
+// request (the POST already reports delivered: 0 when nobody was attached) and
+// only has to say so.
+const ACK_TIMEOUT_MS = 15000;
+
+// After that, it is an inactivity deadline: every frame rearms it, and `wire
+// serve` streams the child's stdout as status frames, so an agent that reports
+// what it is doing keeps its request alive indefinitely. A silent one gets this
+// long. Its work still reaches the page if it lands later, through live-sync,
+// since the wire never carried the content anyway.
+const SILENCE_TIMEOUT_MS = 120000;
+
+// `wire/done` means the handler finished writing the file. It does not mean this
+// page has rendered the change: that arrives on the live-sync lane after the
+// watcher's quiet interval, and nothing orders the two. So a finished request
+// waits in `landing` for the disk frame, and gives up waiting after this.
+const LANDING_TIMEOUT_MS = 4000;
+
+const SAVE_FLUSH_TIMEOUT_MS = 5000;
+
+// A long review session sends many requests. Records outlive their request so a
+// UI can still show what happened, so the map needs a ceiling; terminated ones
+// are dropped oldest-first.
+const MAX_RECORDS = 50;
+
+const OPEN_STATES = new Set(["sent", "acked"]);
+
+// Once a request has ended it stays ended. Several things can arrive after the
+// end and each would otherwise rewrite it: a POST that was already on the wire
+// when the user cancelled, an ack timer that fires after a fast error, a done
+// for a request the handler also errored.
+const TERMINAL_STATES = new Set(["done", "error", "cancelled"]);
+
+const records = new Map();
+const listeners = new Set();
+
+let stream = null;
+let streamReady = null;
+let landingWatch = 0;
+let landingHandler = null;
+
+function newId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `page-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+// Every URL is resolved against the real origin. A `<base href>` in the authored
+// document would otherwise point this page's control channel at an origin the
+// document chose, which is the same trap live-sync documents on its own stream.
+function wireURL(path) {
+  return new URL(path, window.location.origin).href;
+}
+
+function view(rec) {
+  return {
+    id: rec.id,
+    type: rec.type,
+    state: rec.state,
+    text: rec.text,
+    error: rec.error,
+    startedAt: rec.startedAt,
+  };
+}
+
+function emit(rec) {
+  const snapshot = view(rec);
+  for (const fn of listeners) {
+    try {
+      fn(snapshot);
+    } catch (err) {
+      console.error("clay.wire: a listener threw", err);
+    }
+  }
+  document.dispatchEvent(new CustomEvent("clay:wire-state", { detail: snapshot }));
+}
+
+function setState(rec, state) {
+  if (rec.state === state) return;
+  rec.state = state;
+  emit(rec);
+}
+
+// The request deadline. Armed before the POST and rearmed by every frame, so a
+// request is bounded from end to end rather than only up to its ack.
+function arm(rec, ms, message) {
+  clearTimeout(rec.timer);
+  rec.timer = setTimeout(() => {
+    rec.timer = null;
+    finish(rec, "error", message);
+  }, ms);
+}
+
+function disarm(rec) {
+  clearTimeout(rec.timer);
+  rec.timer = null;
+}
+
+function prune() {
+  if (records.size <= MAX_RECORDS) return;
+  for (const [id, rec] of records) {
+    if (records.size <= MAX_RECORDS) break;
+    if (!OPEN_STATES.has(rec.state) && rec.state !== "landing") records.delete(id);
+  }
+}
+
+// --- the stream ------------------------------------------------------------
+
+// A page never names a file and never asks for the handler role. Its target
+// comes from its own URL, through the same funnel live-sync's save uses, and any
+// file it supplied would be discarded server-side; the handler slot is refused
+// to browsers outright, since a page holding it could receive every request on
+// the file, including other tabs', and answer with fabricated terminal frames.
+function openStream() {
+  if (streamReady) return streamReady;
+
+  const path = `/_/wire/subscribe?page-url=${encodeURIComponent(window.location.href)}`;
+  stream = new EventSource(wireURL(path));
+
+  stream.onmessage = (event) => {
+    let frame;
+    try {
+      frame = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    handleFrame(frame);
+  };
+
+  // Native EventSource reconnects on its own and carries Last-Event-ID, and wire
+  // frames are stamped with one, so the server replays any terminal frame this
+  // page missed during the gap: an in-flight request recovers without help. A
+  // request cancelled during the gap is dropped by handleFrame, since its record
+  // is no longer open. What a reconnect cannot bring back is a status frame,
+  // which is display only. So there is nothing to do here.
+  stream.onerror = () => {};
+
+  streamReady = new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.onopen = finish;
+    // Sending is more important than subscribing: a request that never goes out
+    // because the stream would not open is worse than one whose early frames
+    // are missed.
+    setTimeout(finish, 2000);
+  });
+  return streamReady;
+}
+
+function closeStreamIfIdle() {
+  for (const rec of records.values()) {
+    if (OPEN_STATES.has(rec.state)) return;
+  }
+  if (!stream) return;
+  stream.close();
+  stream = null;
+  streamReady = null;
+}
+
+function handleFrame(frame) {
+  if (!frame || typeof frame.id !== "string") return;
+  const rec = records.get(frame.id);
+  // An id this page did not issue, or one it has stopped caring about. Cancel
+  // means stop completely, so a cancelled request's late frames are dropped here
+  // rather than reopening a lifecycle the user ended.
+  if (!rec || !OPEN_STATES.has(rec.state)) return;
+
+  switch (frame.type) {
+    case "wire/ack":
+      // Rearmed, not cleared. The handler acknowledges within milliseconds of
+      // picking a request up, so clearing here would leave every working request
+      // with no deadline at all.
+      arm(rec, SILENCE_TIMEOUT_MS, "the agent stopped responding");
+      setState(rec, "acked");
+      break;
+    case "wire/status":
+      arm(rec, SILENCE_TIMEOUT_MS, "the agent stopped responding");
+      rec.text = typeof frame.text === "string" ? frame.text : "";
+      rec.state = "acked";
+      emit(rec);
+      break;
+    case "wire/done":
+      land(rec);
+      break;
+    case "wire/error":
+      finish(rec, "error", frame.text || "the handler reported an error");
+      break;
+    default:
+      break;
+  }
+}
+
+// --- the landing state -----------------------------------------------------
+
+// `clay:sync-applied` fires on every successful remote morph, from live-sync's
+// single apply choke point, whether or not the sync plugin was loaded by this
+// page's own URL. Listening for it is what makes "done" mean "you can see it"
+// instead of "the agent stopped typing", and it costs no import.
+function watchLandings() {
+  if (landingHandler) return;
+  landingHandler = (event) => {
+    // Both apply paths dispatch this event. A peer frame is another tab's edit,
+    // so completing a landing on one would report done for bytes that are not
+    // the ones this request asked for.
+    if (event.detail?.source === "peer") return;
+    // One record per frame, oldest first (Map iteration is insertion order). A
+    // frame proves one landing and says nothing about any other request, and a
+    // request left waiting still ends on its own next frame or its timer.
+    for (const rec of records.values()) {
+      if (rec.state === "landing") {
+        finish(rec, "done", null);
+        return;
+      }
+    }
+  };
+  document.addEventListener("clay:sync-applied", landingHandler);
+}
+
+function unwatchLandingsIfIdle() {
+  if (landingWatch > 0 || !landingHandler) return;
+  document.removeEventListener("clay:sync-applied", landingHandler);
+  landingHandler = null;
+}
+
+function land(rec) {
+  if (TERMINAL_STATES.has(rec.state) || rec.state === "landing") return;
+  disarm(rec);
+  rec.state = "landing";
+  landingWatch++;
+  watchLandings();
+  rec.landingTimer = setTimeout(() => {
+    // The change may have landed in a way this page cannot observe (no sync
+    // plugin, a frame that morphed nothing). Reporting done late is right;
+    // reporting a working agent as failed is not.
+    finish(rec, "done", null);
+  }, LANDING_TIMEOUT_MS);
+  emit(rec);
+  // The wire is done with this request even though the page is still waiting for
+  // its bytes, so the connection can go now.
+  closeStreamIfIdle();
+}
+
+function finish(rec, state, error) {
+  if (TERMINAL_STATES.has(rec.state)) return;
+  const wasLanding = rec.state === "landing";
+  disarm(rec);
+  clearTimeout(rec.landingTimer);
+  rec.landingTimer = null;
+  // A POST still on the wire has nothing left to report to, and an unbounded
+  // fetch is the one thing the deadline cannot otherwise reach.
+  rec.abort?.abort();
+  if (wasLanding) {
+    landingWatch--;
+    unwatchLandingsIfIdle();
+  }
+  rec.error = error;
+  rec.state = state;
+  releaseSaving(rec);
+  emit(rec);
+  closeStreamIfIdle();
+  prune();
+  if (rec.settle) {
+    const settle = rec.settle;
+    rec.settle = null;
+    settle(view(rec));
+  }
+}
+
+// --- save protection -------------------------------------------------------
+//
+// Two outbound problems the scoped live-sync merge does not touch, because it
+// fixes the return path only.
+//
+// Save before send: autosave is debounced, so a request sent within that window
+// hands the agent a file that does not contain the paragraph the user just typed
+// and is asking about.
+//
+// Suspend autosave while a request is in flight: the save is last-writer-wins
+// with a backup, not a reject. An autosave landing inside the watcher's poll and
+// quiet window posts the pre-agent document, the server backs the agent's bytes
+// up and still writes the browser's, the watcher's revalidation then fails, and
+// nothing is published. The handler reports done, the page shows success, and
+// the agent's work exists only in Backups.
+//
+// The lever is the save lane's own suspension, not a mutation-hub pause. Two
+// reasons. The [persist] input autosave never goes through the hub at all — it is
+// a raw input listener and a timer (autosave.js) — so a hub pause misses the
+// clobber it is supposed to prevent. And pausing the hub blinds the scoped-sync
+// dirty gate, whose one invariant is that it may over-report but must never
+// under-report: a DOM edit the user made during the request would then read as
+// clean, and the agent's frame would full-morph it away.
+
+let saveDepth = 0;
+let saveLane = null;
+
+// Imported lazily and only in edit mode, through one shared promise. The module
+// is not loaded on a view-mode page, so a static import from this
+// `editOnly: false` plugin would drag the save lane into view mode to do nothing.
+let saveLaneReady = null;
+function loadSaveLane() {
+  if (!saveLaneReady) saveLaneReady = import("../core/save.js");
+  return saveLaneReady;
+}
+
+async function holdSaving(rec) {
+  if (!isEditMode || rec.holdsSave) return;
+  // Resolve the module BEFORE claiming the hold. Claiming it first and awaiting
+  // afterwards leaves a window where a cancel releases a hold that was never
+  // taken, and the import that resumes after it suspends a lane nothing will
+  // ever resume.
+  const lane = await loadSaveLane();
+  if (rec.state !== "sent") return;
+  saveLane = lane;
+  rec.holdsSave = true;
+  if (saveDepth++ > 0) return;
+  lane.suspendAutosave();
+}
+
+function releaseSaving(rec) {
+  if (!rec.holdsSave) return;
+  rec.holdsSave = false;
+  if (--saveDepth > 0) return;
+  saveDepth = 0;
+  saveLane?.resumeAutosave();
+}
+
+function once(eventName, timeout) {
+  return new Promise((resolve) => {
+    let done = false;
+    const settle = () => {
+      if (done) return;
+      done = true;
+      document.removeEventListener(eventName, settle);
+      resolve();
+    };
+    document.addEventListener(eventName, settle);
+    setTimeout(settle, timeout);
+  });
+}
+
+/**
+ * Put what the user is looking at on disk, or fail the request.
+ *
+ * The wire's promise is that the agent reads the document the user is asking
+ * about. A flush that could not deliver that has to end the request: posting
+ * anyway means an agent editing a file without the paragraph it was asked about,
+ * silently, which is worse than an error the UI can show.
+ */
+async function flushSave() {
+  if (!isEditMode) return;
+  const clay = window.clay;
+  if (!clay || typeof clay.save !== "function") return;
+
+  // isSaveInProgress comes from the module, not from clay.internals: that
+  // surface is an opt-in satellite script, absent on every page the loader
+  // builds, so reading it here made "is a save on the wire" permanently false.
+  const { isSaveInProgress } = await import("../core/save-core.js");
+  const deadline = Date.now() + SAVE_FLUSH_TIMEOUT_MS;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (isSaveInProgress()) {
+      await once("clay:save-saved", Math.max(0, deadline - Date.now()));
+    }
+
+    const result = await clay.save();
+    // `ok` is the outcome and msgType is the server's severity, so a save that
+    // landed with a warning is a success. `skipped` covers two outcomes: nothing
+    // to save, and a save already on the wire. Only the second means these bytes
+    // never left, and asking whether one is still in progress tells them apart.
+    if (result?.ok) return;
+    if (result?.msgType === "skipped" && !isSaveInProgress()) return;
+    if (result?.msgType === "error" || result?.msgType === "unknown") {
+      throw new Error(`could not save this page first: ${result.msg || result.msgType}`);
+    }
+    if (Date.now() >= deadline) break;
+  }
+  throw new Error("could not save this page before sending");
+}
+
+// --- sending ---------------------------------------------------------------
+
+async function postFrame(body, signal) {
+  const response = await fetch(wireURL("/_/wire/send"), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Page-URL": window.location.href,
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+  let reply = null;
+  try {
+    reply = await response.json();
+  } catch {
+    reply = null;
+  }
+  return { ok: response.ok, status: response.status, reply };
+}
+
+/**
+ * Send one request and track it to a terminal state.
+ *
+ * Returns a handle immediately; `handle.done` resolves with the final snapshot
+ * and never rejects, because a failed request is an outcome the UI renders
+ * rather than an exception it catches.
+ */
+function send(payload, opts = {}) {
+  const id = typeof opts.id === "string" && opts.id ? opts.id : newId();
+  const type = typeof opts.type === "string" && opts.type ? opts.type : "wire/request";
+
+  // The id is request identity on the wire, on both sides: a reused one would
+  // route the first request's frames to the second record, leaving the first
+  // unresolvable and its save hold never released. Refused as an outcome rather
+  // than thrown, so a UI renders it the way it renders any other failure.
+  if (records.has(id)) {
+    const clash = {
+      id,
+      type,
+      state: "error",
+      text: "",
+      error: "a request with this id is already on the wire",
+      startedAt: Date.now(),
+    };
+    return {
+      id,
+      get state() {
+        return clash.state;
+      },
+      done: Promise.resolve(view(clash)),
+      cancel: () => false,
+    };
+  }
+
+  const rec = {
+    id,
+    type,
+    state: "sent",
+    text: "",
+    error: null,
+    startedAt: Date.now(),
+    timer: null,
+    landingTimer: null,
+    abort: typeof AbortController === "function" ? new AbortController() : null,
+    holdsSave: false,
+    settle: null,
+  };
+  rec.done = new Promise((resolve) => {
+    rec.settle = resolve;
+  });
+  records.set(id, rec);
+  emit(rec);
+
+  const dispatch = async () => {
+    // The record is re-checked after every await. A cancel can land in any of
+    // these gaps, and a step that ran on regardless would open a stream nobody
+    // closes or post a request the user already took back.
+    await holdSaving(rec);
+    if (rec.state !== "sent") return;
+
+    await flushSave();
+    if (rec.state !== "sent") return;
+
+    // Subscribe before posting. A handler can acknowledge in single-digit
+    // milliseconds, a fresh subscription deliberately replays nothing, and only
+    // terminal frames are retained at all, so posting first is how a page ends
+    // up watching a request whose ack it already missed.
+    await openStream();
+    if (rec.state !== "sent") {
+      closeStreamIfIdle(); // the stream this cancelled request just opened
+      return;
+    }
+
+    // Armed BEFORE the POST, not after it. A stalled fetch would otherwise leave
+    // the request unbounded, and an ack that arrives while the POST is still in
+    // flight — the ordinary case, since the page subscribed first — would be
+    // followed by a fresh ack timer that fails a healthy request 15s later.
+    arm(rec, ACK_TIMEOUT_MS, "the agent never answered");
+
+    const { ok, status, reply } = await postFrame(
+      { type: rec.type, id: rec.id, text: opts.text, payload },
+      rec.abort?.signal
+    );
+
+    // A frame may have moved this request on while its own POST was in flight.
+    // Only a request still waiting on that POST may be failed by it.
+    if (rec.state !== "sent") return;
+
+    if (!ok) {
+      finish(rec, "error", `the wire refused this request (${status})`);
+      return;
+    }
+    if (!reply || reply.delivered === 0) {
+      // Accepted by the router and taken by nobody. Reporting this as an error
+      // rather than a pending request is the difference between a UI that says
+      // "start an agent" and one that spins forever.
+      finish(rec, "error", "no agent is attached to this file");
+    }
+  };
+
+  dispatch().catch((err) => {
+    finish(rec, "error", err && err.message ? err.message : String(err));
+  });
+
+  return {
+    id,
+    get state() {
+      return rec.state;
+    },
+    done: rec.done,
+    cancel: () => cancel(id),
+  };
+}
+
+/**
+ * Stop completely: the request ends here, its late frames are ignored, and the
+ * handler is asked to stop. A cancel that only hid the spinner would leave the
+ * agent writing the file the user just took back.
+ */
+function cancel(id) {
+  const rec = records.get(id);
+  if (!rec || !OPEN_STATES.has(rec.state)) return false;
+  postFrame({ type: "wire/cancel", id }).catch(() => {});
+  finish(rec, "cancelled", null);
+  return true;
+}
+
+function get(id) {
+  const rec = records.get(id);
+  return rec ? view(rec) : undefined;
+}
+
+function list() {
+  return [...records.values()].map(view);
+}
+
+function isBusy() {
+  for (const rec of records.values()) {
+    if (OPEN_STATES.has(rec.state)) return true;
+  }
+  return false;
+}
+
+function on(fn) {
+  if (typeof fn !== "function") return () => {};
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+export const wire = { send, cancel, get, list, isBusy, on };
+
+export default wire;