lavish-axi 0.1.64 → 0.1.66

package/README.md

@@ -199,6 +199,7 @@ pnpm link
   Mark only custom (non-native) clickable elements with `data-lavish-action` so Lavish does not annotate them, and use `data-lavish-question` or `queueKey` when pre-send updates for the same question should replace each other.
   On wider screens, queued annotation preview pills and chat history share a scrollable Conversation panel above a sticky composer, so long feedback queues do not push the text box or send controls off screen.
   The browser chrome keeps editing actions in the overflow menu (copy path, reload artifact, copy DOM snapshot, export standalone HTML, publish link, end session), while the composer exposes **Send & End** beside **Send to Agent** to submit queued prompts and user-ended attribution together.
+  Composer feedback is visibly queued before the text box clears and stays queued until acknowledged, with persistent recovery guidance if sending fails or takes longer than 10 seconds.
 - **Reviewing on a phone** - Below 860px wide, the artifact takes the whole screen above a **Conversation** dock, and the conversation opens as a bottom sheet over it: tap the dock, swipe it up, or press the chevron to raise it; tap the dimmed artifact, swipe the sheet down, press the chevron, or press Escape to lower it. The dock reports what matters while the sheet is down - how many prompts are queued, a reply that arrived while you were reading, or whether the agent is listening - and the sheet stays open across a reload of the review page. The sheet sizes itself to the visible viewport and respects safe-area insets; if the keyboard or attachments leave little room, conversation content yields or scrolls while the send actions remain pinned above the bottom edge. In landscape the sheet covers the top bar as well. Wider screens keep the side-by-side layout.
 - **Keyboard shortcuts** - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline.
   In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately. Escape closes the card, same as Cancel, but only while it is empty (no text, no attachment); with unsent text or an attachment present, Escape does nothing rather than risk discarding it.
@@ -234,6 +235,7 @@ pnpm link
 - **Server cleanup** - The detached server stops after the last session ends when nothing is connected, or after `LAVISH_AXI_IDLE_TIMEOUT_MS` (default 30 minutes) with no browser or poll connections.
   Set `LAVISH_AXI_IDLE_TIMEOUT_MS=0` or `off` to disable idle self-shutdown.
 - **Server upgrades** - One background server serves every session, so upgrading `lavish-axi` while reviews are open makes the next `lavish-axi <html-file>` replace that server. Only the review page for the artifact being opened reloads itself once the replacement answers - and not even that one while you have unsent annotation text open, which gets the same banner instead so the reload is yours to make. Every other open review page keeps working and shows a banner reading "Lavish was updated. This page is running the previous version.", with a Check and reload button and a Dismiss button, so no page you are reading reloads on its own. After `lavish-axi stop` those pages say Lavish was stopped and to reload after you start it again, and a restart that only picks up a local build says that rather than claiming an update.
+  A page still using the legacy event stream reloads once when it reconnects to the replacement server, moving itself onto the current transport without retaining an HTTP connection. If unsent annotation text is open, it shows the neutral server-restarted banner instead and waits for you to reload.
   Every **Check and reload** control asks the server whether it is running before it navigates; while nothing answers, the page stays where it is and says so, and a check that gets no answer at all says that instead of guessing.
   In-flight `lavish-axi poll` commands end with an interrupted-poll error and are safe to re-run; queued feedback is never lost, and annotation text you have typed but not queued yet survives the reload as described under **Live reload**.
   A page waits for the replacement rather than reloading into a port nothing is listening on, and tells the user to restart Lavish if it never returns.

package/dist/chrome-client.js

@@ -1,4 +1,4 @@
-/* global EventSource, document, location, window */
+/* global document, location, window */
 
 const sessionDataElement = document.getElementById("lavish-session");
 const sessionData = JSON.parse(sessionDataElement?.textContent || "{}");
@@ -216,6 +216,8 @@ let endAfterSubmit = false;
 let workingBubble = null;
 let submitQueuedPromise = null;
 let submitQueuedAgain = false;
+/** @type {ReturnType<typeof setTimeout> | undefined} */
+let sendAcknowledgementTimer;
 let lastScroll = { x: 0, y: 0 };
 // In-iframe review context (an open annotation card's unsent text, Lavish-owned question
 // answers). The sandbox means the chrome cannot read it back after a reload, so the SDK reports
@@ -243,6 +245,14 @@ const CHROME_RESTART_PROBE_MS = 100;
 const CHROME_RESTART_SLOW_PROBE_MS = 500;
 // A probe must always settle, so the control that is waiting on it always comes back.
 const HEALTH_PROBE_TIMEOUT_MS = 4000;
+// A send starts before the artifact snapshot arrives and ends only when /prompts acknowledges the
+// batch. Bound that whole wait so a missing SDK response or a browser/network stall can never look
+// like a dead button while the user's queue remains safely stored in this tab.
+const SEND_ACKNOWLEDGEMENT_WARNING_MS = 10_000;
+const SEND_STALLED_COPY =
+  "Still trying to send. Your feedback is saved in this tab. Keep this tab open while Lavish catches up, and check that the server is running.";
+const SEND_FAILED_COPY =
+  "Could not send. Your feedback is still queued in this tab. Check that Lavish is running, then click Send to Agent to retry.";
 const HEALTH_NO_ANSWER_TITLE = "Lavish did not answer.";
 const HEALTH_NO_ANSWER_COPY =
   "Lavish did not answer the check, so this page cannot tell whether it is running. Try again in a moment.";
@@ -263,6 +273,7 @@ let artifactSilenceTimer;
 let copyHintTimer;
 /** @type {ReturnType<typeof setTimeout> | undefined} */
 let sendHintTimer;
+let sendHintPersistent = false;
 
 function artifactFrameSrcForLoad(load) {
   const separator = artifactSrc.includes("?") ? "&" : "?";
@@ -476,20 +487,50 @@ function pillAttachmentsHtml(prompt) {
 
 const DEFAULT_SEND_HINT = "Write a message or annotate an element first.";
 
-function showSendHint(message = DEFAULT_SEND_HINT, holdMs = 2600) {
+function showSendHint(message = DEFAULT_SEND_HINT, holdMs = 2600, focusInput = true) {
   sendHint.textContent = message;
   sendHint.hidden = false;
   clearTimeout(sendHintTimer);
+  sendHintPersistent = holdMs === null;
+  sendHint.classList.toggle("persistent", sendHintPersistent);
+  if (sendHintPersistent) {
+    sendHintTimer = undefined;
+    if (focusInput) chatInput.focus();
+    return;
+  }
   sendHintTimer = setTimeout(() => {
     sendHint.hidden = true;
     sendHint.textContent = DEFAULT_SEND_HINT;
+    sendHintPersistent = false;
   }, holdMs);
-  chatInput.focus();
+  if (focusInput) chatInput.focus();
 }
 
-function hideSendHint() {
+function hideSendHint(force = false) {
+  if (sendHintPersistent && force !== true) return;
   clearTimeout(sendHintTimer);
   sendHint.hidden = true;
+  sendHint.textContent = DEFAULT_SEND_HINT;
+  sendHint.classList.remove("persistent");
+  sendHintPersistent = false;
+}
+
+function armSendAcknowledgementWarning() {
+  if (sendAcknowledgementTimer || !queued.length) return;
+  sendAcknowledgementTimer = setTimeout(() => {
+    sendAcknowledgementTimer = undefined;
+    if (queued.length) showSendHint(SEND_STALLED_COPY, null, false);
+  }, SEND_ACKNOWLEDGEMENT_WARNING_MS);
+}
+
+function clearSendAcknowledgementWarning() {
+  clearTimeout(sendAcknowledgementTimer);
+  sendAcknowledgementTimer = undefined;
+}
+
+function showQueuedSendFailure(message = SEND_FAILED_COPY) {
+  clearSendAcknowledgementWarning();
+  if (queued.length) showSendHint(message, null, false);
 }
 
 function setMenuOpen(button, menu, open) {
@@ -583,15 +624,6 @@ function setHandoffSuperseded(visible) {
 // the shutdown names its reason and each one gets its own line - a page told "Lavish was updated"
 // after a deliberate stop is being told something false. An unnamed reason (SIGTERM, or any
 // caller that names none) claims neither.
-// Both shutdown events carry the reason the same way, so both render from one rule.
-function shutdownEventReason(event) {
-  try {
-    return String(JSON.parse(event?.data || "{}").reason || "");
-  } catch {
-    return "";
-  }
-}
-
 function chromeOutdatedCopy(reason) {
   if (reason === "upgrade") return "Lavish was updated. This page is running the previous version.";
   if (reason === "local-build") {
@@ -909,6 +941,10 @@ function removeQueuedPrompt(index, event) {
   if (event) event.stopPropagation();
   queued.splice(index, 1);
   persistQueuedPrompts();
+  if (!queued.length) {
+    clearSendAcknowledgementWarning();
+    hideSendHint(true);
+  }
   render();
 }
 
@@ -1170,17 +1206,20 @@ function sendQueued(endAfter) {
       if (attachments.length) prompt.attachments = attachments;
       queued.push(prompt);
       persistQueuedPrompts();
+      // Render the durable queue pill before clearing the editor. If anything after this point
+      // fails, the user's words are already both stored and visibly recoverable in the tab.
+      render();
       addChat("user", text || "Image message");
       chatInput.value = "";
       chatAttachmentController.reset();
-      render();
     }
   }
   if (!queued.length) {
     if (!chipsBlocked) showSendHint();
     return;
   }
-  hideSendHint();
+  hideSendHint(true);
+  armSendAcknowledgementWarning();
 
   if (endAfter && !chipsBlocked) endAfterSubmit = true;
   requestSnapshot("submit");
@@ -1220,24 +1259,34 @@ async function submitQueuedOnce() {
   const shouldEndSession = endAfterSubmit;
   const body = { prompts: prompts.map(stripInternalPromptFields), domSnapshot: pendingSnapshot };
   if (shouldEndSession) body.endSession = true;
-  const response = await fetch("/api/" + key + "/prompts", {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-  });
+  let response;
+  try {
+    response = await fetch("/api/" + key + "/prompts", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (error) {
+    showQueuedSendFailure();
+    throw error;
+  }
   if (!response.ok) {
     if (response.status === 409) {
       const data = await response.json().catch(() => null);
       // The session already ended before this batch arrived - most likely this chrome missed the
-      // SSE `ended` event (a dropped connection). Go read-only now instead of leaving Send enabled
+      // live `ended` event (a dropped connection). Go read-only now instead of leaving Send enabled
       // for another attempt that will be refused the same way.
       if (data?.status === "ended") {
+        clearSendAcknowledgementWarning();
         endAfterSubmit = false;
         markSessionEnded();
         return false;
       }
       if (Array.isArray(data?.warnings)) setLayoutWarnings(data.warnings);
       endAfterSubmit = false;
+      showQueuedSendFailure(
+        "Could not send because the layout issue selection changed. Your feedback is still queued. Review the current issues, then click Send to Agent to retry.",
+      );
       return false;
     }
     // C4: the server persisted nothing (atomic reject) - the queue below is left
@@ -1246,8 +1295,12 @@ async function submitQueuedOnce() {
     if (response.status === 400) {
       const detail = await response.json().catch(() => ({}));
       if (Array.isArray(detail.rejected) && detail.rejected.length) {
-        showSendHint(describeAttachmentRejection(detail.rejected, detail.caps), 6000);
+        showQueuedSendFailure(describeAttachmentRejection(detail.rejected, detail.caps));
+      } else {
+        showQueuedSendFailure();
       }
+    } else {
+      showQueuedSendFailure();
     }
     throw new Error("failed to submit queued prompts");
   }
@@ -1257,6 +1310,9 @@ async function submitQueuedOnce() {
   }
   persistQueuedPrompts();
   render();
+  clearSendAcknowledgementWarning();
+  hideSendHint(true);
+  if (queued.length) armSendAcknowledgementWarning();
   if (shouldEndSession) {
     endAfterSubmit = false;
     markSessionEnded();
@@ -3178,7 +3234,7 @@ chatComposer.addEventListener("drop", (event) => {
   chatAttachmentController.rejectUnsupported(files);
 });
 // A file drop that misses the composer must not navigate the chrome away from
-// the session (losing chips, uploads, and the SSE connection). Text drags stay
+// the session (losing chips, uploads, and the live-event connection). Text drags stay
 // untouched so dropping text into the textarea keeps working.
 document.addEventListener("dragover", (event) => {
   if (Array.from(event.dataTransfer?.types || []).includes("Files")) event.preventDefault();
@@ -3199,7 +3255,7 @@ chatInput.addEventListener("keydown", (event) => {
     sendQueued(false);
   }
 });
-chatInput.addEventListener("input", hideSendHint);
+chatInput.addEventListener("input", () => hideSendHint());
 copyPathButton.onclick = copyFilePath;
 reloadArtifactButton.onclick = reloadArtifact;
 copySnapshotButton.onclick = copyDomSnapshot;
@@ -3278,27 +3334,48 @@ frame.addEventListener("load", () => {
 
 initializeLayoutGate();
 
-const events = new EventSource("/events/" + key);
-events.addEventListener("reload", () => {
+// WebSockets leave the browser's HTTP connection pool free for sends and artifact loads.
+const events = new Map();
+let eventReconnectDelayMs = 500;
+function connectLiveEvents() {
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  const socket = new WebSocket(protocol + "//" + location.host + "/events/" + encodeURIComponent(key));
+  socket.addEventListener("open", () => {
+    eventReconnectDelayMs = 500;
+    refreshLayoutWarnings();
+  });
+  socket.addEventListener("message", (message) => {
+    try {
+      const { type, data } = JSON.parse(message.data);
+      return events.get(type)?.(data || {});
+    } catch {
+      // Ignore malformed frames; a later event or reconnect can recover the stream.
+    }
+  });
+  socket.addEventListener("close", () => {
+    setTimeout(connectLiveEvents, eventReconnectDelayMs);
+    eventReconnectDelayMs = Math.min(eventReconnectDelayMs * 2, 5000);
+  });
+}
+
+events.set("reload", () => {
   resetFrame().then((reloaded) => {
     if (reloaded) refreshWhiteboardSource();
   });
 });
-events.addEventListener("chrome-reload", (event) => reloadAfterServerRestart(shutdownEventReason(event)));
+events.set("chrome-reload", (data) => reloadAfterServerRestart(String(data.reason || "")));
 // The replacement server serves a different artifact's review. This page keeps working against
 // it; it is only running the previous version of the chrome, which is the user's to act on.
-events.addEventListener("chrome-outdated", (event) => setChromeOutdated(true, shutdownEventReason(event)));
-events.addEventListener("agent-reply", (event) => {
-  const text = JSON.parse(event.data).text;
+events.set("chrome-outdated", (data) => setChromeOutdated(true, String(data.reason || "")));
+events.set("agent-reply", ({ text }) => {
   addChat("agent", text);
   noteAgentReply(text);
 });
-events.addEventListener("chat-sync", (event) => syncChat(JSON.parse(event.data).chat || []));
-events.addEventListener("agent-presence", (event) => setAgentPresence(JSON.parse(event.data).state));
-events.addEventListener("layout-warnings", (event) => setLayoutWarnings(JSON.parse(event.data).warnings || []));
-events.addEventListener("ended", () => markSessionEnded());
-// A reconnecting stream means this chrome may have missed updates while it was away.
-events.addEventListener("open", () => refreshLayoutWarnings());
+events.set("chat-sync", (data) => syncChat(data.chat || []));
+events.set("agent-presence", (data) => setAgentPresence(data.state));
+events.set("layout-warnings", (data) => setLayoutWarnings(data.warnings || []));
+events.set("ended", () => markSessionEnded());
+connectLiveEvents();
 
 applySheetState();
 render();
@@ -3308,7 +3385,7 @@ renderWarnings();
 initialChat.forEach((item) => addChat(item.role, item.text));
 retiredDrafts.forEach((text) => renderRetiredDraft(text));
 setAgentPresence("waiting");
-// The session already ended before this page (re)loaded, so there is no future SSE `ended` event
+// The session already ended before this page (re)loaded, so there is no future live `ended` event
 // to wait for - start read-only instead of looking live until a Send gets silently refused.
 if (sessionData.initialEnded) markSessionEnded();
 

package/dist/chrome.css

@@ -1300,6 +1300,13 @@ body.lavish {
   font-size: 11px;
   line-height: 1.35;
 }
+.send-hint.persistent {
+  padding: var(--space-4);
+  border: 1px solid var(--amber-700);
+  border-radius: var(--radius-sm);
+  background: var(--amber-900);
+  color: var(--accent-hover);
+}
 .send-hint[hidden] {
   display: none;
 }

package/dist/cli.mjs

@@ -78,7 +78,8 @@ var PLAYBOOKS = [
     ],
     lavish_notes: [
       "A Lavish table should make individual rows easy annotation targets.",
-      "If a row implies a follow-up change, include an action control that queues a specific prompt."
+      "If a row implies a follow-up change, include an action control that queues a specific prompt.",
+      "When one action covers multiple rows and completeness matters, also follow the input playbook's tracked batch pattern so the reviewer submits one explicit ID set for item-by-item accounting."
     ]
   },
   {
@@ -201,10 +202,12 @@ var PLAYBOOKS = [
     choose: [
       "Use this when the user needs to select, tune, triage, annotate, or edit a structured choice.",
       "Use controls for decisions the user can make faster visually than by writing a prompt.",
+      "Use an opt-in tracked batch when the agent must preserve completeness across a multi-item decision, such as findings to fixes, constraints to implementation, or recommendations to follow-up work.",
       "Use plain annotations when the artifact only needs open-ended feedback."
     ],
     structure: [
       "Make each decision surface visible: what is being chosen, what the options mean, and what happens next.",
+      "For a tracked batch, give every candidate item a short, stable, visible ID and let the reviewer select or disposition items with editable native controls.",
       "Keep reversible selection state local in the artifact until the user explicitly submits that question.",
       "Pair each question with a Submit or Queue answer control that sends exactly one prompt for the final answer.",
       "Show selected state separately from queued state so the user trusts what will be sent back."
@@ -216,6 +219,7 @@ var PLAYBOOKS = [
       "Put data-lavish-action only on custom (non-native) elements that should act like a feedback control - typically a styled div or span you made clickable - so Lavish does not annotate it and shows a pointer cursor instead.",
       "Use data-lavish-question on a question wrapper or pass queueKey when multiple pre-send updates should replace the prior unsent answer for the same question.",
       "Pass options such as tag, text, selector, target, data, queueKey, or element when they help the agent understand exactly what the user chose.",
+      "For a tracked batch, queue the final selected set once in a concise, bounded data.items array; include each item's stable ID, concise label, and requested disposition, and explicitly tell the agent to account for every submitted ID before reporting completion.",
       "Call window.lavish.sendQueuedPrompts() only when the control should immediately send committed feedback instead of waiting for the user to press Send to Agent.",
       "Make queued prompts specific enough that the agent can act without asking a follow-up question.",
       "Keep native browser controls accessible and readable on mobile."
@@ -229,6 +233,8 @@ var PLAYBOOKS = [
     lavish_notes: [
       "Lavish is strongest when the artifact becomes a focused review surface and not just a static page.",
       `A native single-choice question should submit the final value: \`<form data-lavish-question="plan" onsubmit="event.preventDefault(); const choice = new FormData(event.currentTarget).get('plan'); if (choice) window.lavish.queuePrompt('Use the ' + choice + ' plan', { tag: 'choice', text: 'Plan: ' + choice, element: event.currentTarget, data: { question: 'plan', answer: choice } });"><label><input type="radio" name="plan" value="Starter"> Starter</label><label><input type="radio" name="plan" value="Pro"> Pro</label><button type="submit">Queue this answer</button></form>\`.`,
+      `A tracked batch should submit the final selected set once: <form data-lavish-question="tracked-review" onsubmit="event.preventDefault(); const selected = [...event.currentTarget.querySelectorAll('input[name=items]:checked')].map((input) => ({ id: input.value, label: input.dataset.label, disposition: input.dataset.disposition })); if (selected.length) window.lavish.queuePrompt('Act on every selected item and return an item-by-item receipt. Account for every submitted ID before reporting completion.', { tag: 'tracked-batch', text: 'Apply ' + selected.length + ' selected review items', element: event.currentTarget, data: { items: selected } });"><label><input type="checkbox" name="items" value="R-03" data-label="Preserve rollback behavior" data-disposition="must-address"> R-03 \u2014 Preserve rollback behavior</label><label><input type="checkbox" name="items" value="R-08" data-label="Reuse the existing error surface" data-disposition="must-address"> R-08 \u2014 Reuse the existing error surface</label><button type="submit">Queue selected items</button></form>`,
+      "The agent's tracked-batch completion receipt must give every submitted ID exactly one outcome: addressed with concrete evidence, deferred with a reason, or rejected with a reason. Evidence may cover several IDs. Before declaring completion, compare the submitted ID set with the receipt ID set and surface every missing ID.",
       "A custom choice UI should make option buttons update local state, then use a separate Queue answer button with data-lavish-action to queue the final selected value.",
       "Use window.lavish.queuePrompt for user intent, not internal analytics or UI-only state changes.",
       "End input paths with an obvious way for the user to send feedback back to the agent."
@@ -8806,6 +8812,7 @@ var DEFAULT_IDLE_TIMEOUT_MS = 30 * 6e4;
 var WHITEBOARD_CHANNEL_TOKEN_TTL_MS = 5 * 6e4;
 var NETWORK_RECONCILE_CACHE_MS = 1e3;
 var TAILSCALE_BIND_RETRY_DELAYS_MS = [100, 250, 500];
+var WEBSOCKET_CLOSE_GRACE_MS = 250;
 var ARTIFACT_CONTENT_SECURITY_POLICY = "sandbox allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads";
 var ATTACHMENT_SWEEP_INTERVAL_MS = 60 * 6e4;
 var SHUTDOWN_REASONS = /* @__PURE__ */ new Set(["upgrade", "local-build", "stop"]);
@@ -8912,6 +8919,7 @@ async function serve({
   lookupHost,
   whiteboardAssetsDir = defaultWhiteboardAssetsDir()
 } = {}) {
+  const { WebSocket, WebSocketServer } = await import("ws");
   const extraHosts = allowedHosts ?? extraAllowedHosts(env);
   const envHost = env.LAVISH_AXI_HOST?.trim();
   const autoTailscale = !envHost;
@@ -8933,7 +8941,7 @@ async function serve({
   const watchers = /* @__PURE__ */ new Map();
   const activePolls = /* @__PURE__ */ new Map();
   const deliveredFeedback = /* @__PURE__ */ new Set();
-  const sseClients = /* @__PURE__ */ new Map();
+  const liveEventClients = /* @__PURE__ */ new Map();
   const whiteboardChannelSecret = crypto6.randomBytes(32);
   const outstandingRepairBatches = /* @__PURE__ */ new Set();
   const diagnosticViewportClasses = resolveDiagnosticViewportClasses();
@@ -8947,6 +8955,39 @@ async function serve({
   let networkReconcileCheckedAt = 0;
   let cachedNetworkStale = false;
   let networkReconcilePromise = null;
+  function broadcastLiveEvent(type, key, data = {}) {
+    for (const [client, clientKey] of liveEventClients) {
+      if (clientKey === key) client.sendEvent(type, data);
+    }
+  }
+  events.on("reload", (key) => broadcastLiveEvent("reload", key));
+  events.on("agent-reply", (key, text) => broadcastLiveEvent("agent-reply", key, { text }));
+  events.on("agent-presence", (key, state) => broadcastLiveEvent("agent-presence", key, { state }));
+  events.on("layout-warnings", (key, warnings) => broadcastLiveEvent("layout-warnings", key, { warnings }));
+  events.on("ended", (key, endedBy) => broadcastLiveEvent("ended", key, { ended_by: endedBy || null }));
+  function attachLiveEventClient(client, key, onClose) {
+    liveEventClients.set(client, key);
+    refreshIdleTimer();
+    let cleanedUp = false;
+    const cleanup = () => {
+      if (cleanedUp) return;
+      cleanedUp = true;
+      liveEventClients.delete(client);
+      refreshIdleTimer();
+    };
+    onClose(cleanup);
+    return cleanup;
+  }
+  async function sendInitialLiveEventState(client, key, cleanup) {
+    const session = await store.findByKey(key);
+    if (client.isClosed()) {
+      cleanup();
+      return;
+    }
+    client.sendEvent("chat-sync", { chat: session?.chat || [] });
+    client.sendEvent("agent-presence", { state: computePresence(key, activePolls, deliveredFeedback) });
+    if (session?.status === "ended") client.sendEvent("ended", { ended_by: session.ended_by || null });
+  }
   async function reconcileTailscaleNetwork() {
     if (Date.now() - networkReconcileCheckedAt < NETWORK_RECONCILE_CACHE_MS) return cachedNetworkStale;
     if (networkReconcilePromise) return networkReconcilePromise;
@@ -9637,93 +9678,16 @@ async function serve({
       next(error);
     }
   });
-  app.get("/events/:key", async (req, res, next) => {
-    let cleanup = () => {
-    };
-    try {
-      res.writeHead(200, {
-        "content-type": "text/event-stream",
-        "cache-control": "no-cache",
-        connection: "keep-alive"
-      });
-      sseClients.set(res, String(req.params.key || ""));
-      refreshIdleTimer();
-      const sendReload = (key) => {
-        if (key === req.params.key) {
-          res.write("event: reload\ndata: {}\n\n");
-        }
-      };
-      const sendAgentReply = (key, text) => {
-        if (key === req.params.key) {
-          res.write(`event: agent-reply
-data: ${JSON.stringify({ text })}
-
-`);
-        }
-      };
-      const sendPresence = (key, state) => {
-        if (key === req.params.key) {
-          res.write(`event: agent-presence
-data: ${JSON.stringify({ state })}
-
-`);
-        }
-      };
-      const sendLayoutWarnings = (key, warnings) => {
-        if (key === req.params.key) {
-          res.write(`event: layout-warnings
-data: ${JSON.stringify({ warnings })}
-
-`);
-        }
-      };
-      const sendEnded = (key, endedBy) => {
-        if (key === req.params.key) {
-          res.write(`event: ended
-data: ${JSON.stringify({ ended_by: endedBy || null })}
-
-`);
-        }
-      };
-      events.on("reload", sendReload);
-      events.on("agent-reply", sendAgentReply);
-      events.on("agent-presence", sendPresence);
-      events.on("layout-warnings", sendLayoutWarnings);
-      events.on("ended", sendEnded);
-      let cleanedUp = false;
-      cleanup = () => {
-        if (cleanedUp) return;
-        cleanedUp = true;
-        req.off("close", cleanup);
-        sseClients.delete(res);
-        events.off("reload", sendReload);
-        events.off("agent-reply", sendAgentReply);
-        events.off("agent-presence", sendPresence);
-        events.off("layout-warnings", sendLayoutWarnings);
-        events.off("ended", sendEnded);
-        refreshIdleTimer();
-      };
-      req.once("close", cleanup);
-      const session = await store.findByKey(req.params.key);
-      if (req.destroyed || res.writableEnded) {
-        cleanup();
-        return;
-      }
-      res.write(`event: chat-sync
-data: ${JSON.stringify({ chat: session?.chat || [] })}
+  app.get("/events/:key", (_req, res) => {
+    res.writeHead(200, {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "close"
+    });
+    res.end(`event: chrome-reload
+data: ${JSON.stringify({ reason: "server-restarted" })}
 
 `);
-      res.write(
-        `event: agent-presence
-data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, deliveredFeedback) })}
-
-`
-      );
-      if (session?.status === "ended") sendEnded(req.params.key, session.ended_by);
-    } catch (error) {
-      cleanup();
-      next(error);
-    }
   });
   app.get("/chrome-client.js", async (req, res, next) => {
     try {
@@ -9965,6 +9929,74 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
     const status = Number(error?.statusCode || error?.status) || 500;
     res.status(status).json({ error: error instanceof Error ? error.message : String(error) });
   });
+  const eventWebSocketServer = new WebSocketServer({ noServer: true, maxPayload: 1024 });
+  function rejectEventUpgrade(socket, status, message) {
+    const body = `${message}
+`;
+    socket.end(
+      `HTTP/1.1 ${status} ${message}\r
+Connection: close\r
+Content-Type: text/plain; charset=utf-8\r
+Content-Length: ${Buffer.byteLength(body)}\r
+\r
+${body}`
+    );
+  }
+  function handleEventUpgrade(req, socket, head) {
+    let pathname;
+    try {
+      pathname = new URL(String(req.url || ""), "http://lavish.local").pathname;
+    } catch {
+      rejectEventUpgrade(socket, 400, "Bad Request");
+      return;
+    }
+    const match = pathname.match(/^\/events\/([^/]+)$/);
+    if (!match) {
+      rejectEventUpgrade(socket, 404, "Not Found");
+      return;
+    }
+    const hostAllowed = allowAnyHostname ? parseHostAuthority(req.headers.host) !== null : isAllowedRequestHost(
+      { host: req.headers.host, forwardedHost: req.headers["x-forwarded-host"] },
+      allowedHostnames
+    );
+    if (!hostAllowed || !req.headers.origin || !isSameOriginRequest(req, allowedHostnames, allowAnyHostname)) {
+      rejectEventUpgrade(socket, 403, "Forbidden");
+      return;
+    }
+    let key;
+    try {
+      key = decodeURIComponent(match[1]);
+    } catch {
+      rejectEventUpgrade(socket, 400, "Bad Request");
+      return;
+    }
+    eventWebSocketServer.handleUpgrade(req, socket, head, (webSocket) => {
+      const client = {
+        sendEvent(type, data) {
+          if (webSocket.readyState === WebSocket.OPEN) webSocket.send(JSON.stringify({ type, data }));
+        },
+        close(code = 1001, reason = "Lavish server shutdown") {
+          webSocket.close(code, reason);
+          const terminateTimer = setTimeout(() => {
+            if (webSocket.readyState !== WebSocket.CLOSED) webSocket.terminate();
+          }, WEBSOCKET_CLOSE_GRACE_MS);
+          terminateTimer.unref?.();
+          webSocket.once("close", () => clearTimeout(terminateTimer));
+        },
+        isClosed() {
+          return webSocket.readyState === WebSocket.CLOSING || webSocket.readyState === WebSocket.CLOSED;
+        }
+      };
+      webSocket.on("error", () => {
+      });
+      const cleanup = attachLiveEventClient(client, key, (remove) => webSocket.once("close", remove));
+      sendInitialLiveEventState(client, key, cleanup).catch((error) => {
+        client.close(1011, "Failed to initialize live events");
+        cleanup();
+        logEvent?.(`event WebSocket initialization failed session=${key}: ${error?.message || error}`);
+      });
+    });
+  }
   const httpServers = [];
   const boundHosts = [];
   let boundPort = port;
@@ -9974,6 +10006,7 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
     while (true) {
       try {
         const httpServer = await listenHttp(app, boundPort, listenHost);
+        httpServer.on("upgrade", handleEventUpgrade);
         if (boundPort === 0) boundPort = httpServer.address().port;
         httpServers.push(httpServer);
         boundHosts.push(listenHost);
@@ -10024,25 +10057,19 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
       clearInterval(attachmentSweepTimer);
       attachmentSweepTimer = null;
     }
-    const shutdownData = JSON.stringify({ reason });
-    for (const [res, clientKey] of sseClients) {
+    const shutdownData = { reason };
+    for (const [client, clientKey] of liveEventClients) {
       try {
         if (reloadKey && clientKey === reloadKey) {
-          res.write(`event: chrome-reload
-data: ${shutdownData}
-
-`);
+          client.sendEvent("chrome-reload", shutdownData);
         } else {
-          res.write(`event: chrome-outdated
-data: ${shutdownData}
-
-`);
+          client.sendEvent("chrome-outdated", shutdownData);
         }
-        res.end();
+        client.close();
       } catch {
       }
     }
-    sseClients.clear();
+    liveEventClients.clear();
     for (const w of watchers.values()) {
       w.close().catch(() => {
       });
@@ -10067,10 +10094,10 @@ data: ${shutdownData}
       idleTimer = null;
     }
     if (shuttingDown || idleTimeoutMs == null) return;
-    if (sseClients.size > 0 || activePolls.size > 0) return;
+    if (liveEventClients.size > 0 || activePolls.size > 0) return;
     idleTimer = setTimeout(() => {
       idleTimer = null;
-      if (!shuttingDown && sseClients.size === 0 && activePolls.size === 0) {
+      if (!shuttingDown && liveEventClients.size === 0 && activePolls.size === 0) {
         logEvent?.(`idle for ${idleTimeoutMs}ms with no connections, shutting down`);
         shutdown();
       }
@@ -10078,7 +10105,7 @@ data: ${shutdownData}
     idleTimer.unref?.();
   }
   async function shutdownIfNoLiveSessions() {
-    if (sseClients.size > 0 || activePolls.size > 0) return;
+    if (liveEventClients.size > 0 || activePolls.size > 0) return;
     try {
       const sessions = await store.listSessions();
       if (sessions.every((session) => session.status === "ended")) {
@@ -10273,24 +10300,24 @@ function hasPresentOriginOrReferer(req) {
 function isSameOriginRequest(req, allowedHostnames, allowAnyHostname = false) {
   const host = parseHostAuthority(req.headers.host);
   if (!host) return false;
-  let protocol = req.protocol;
+  let protocol = req.protocol || "http";
   let authority = host;
-  const forwardedHost = String(req.get("x-forwarded-host") || "").split(",").pop().trim();
+  const forwardedHost = String(req.headers["x-forwarded-host"] || "").split(",").pop().trim();
   if (forwardedHost) {
     const forwardedAuthority = parseHostAuthority(forwardedHost);
     if (!forwardedAuthority || !allowAnyHostname && (!allowedHostnames.has(host.hostname) || !allowedHostnames.has(forwardedAuthority.hostname)))
       return false;
-    protocol = String(req.get("x-forwarded-proto") || req.protocol).split(",").pop().trim().toLowerCase();
+    protocol = String(req.headers["x-forwarded-proto"] || protocol).split(",").pop().trim().toLowerCase();
     if (protocol !== "http" && protocol !== "https") return false;
     authority = forwardedAuthority;
   }
   const expectedOrigin = normalizeOrigin(`${protocol}://${authority.authority}`);
   if (!expectedOrigin) return false;
-  const origin = req.get("origin");
+  const origin = req.headers.origin;
   if (origin) {
     return normalizeOrigin(origin) === expectedOrigin;
   }
-  const referer = req.get("referer");
+  const referer = req.headers.referer;
   return Boolean(referer) && normalizeOrigin(referer) === expectedOrigin;
 }
 function normalizeOrigin(value) {
@@ -10584,7 +10611,7 @@ function createChromeHtml(session, {
   const sessionJson = jsonScript({
     key: session.key,
     file: session.file,
-    // A page loaded (or reloaded) after the session already ended has no future SSE `ended`
+    // A page loaded (or reloaded) after the session already ended has no future live `ended`
     // event to wait for - it must start read-only instead of looking live until the user tries
     // to send and gets refused (#171).
     initialEnded: session.status === "ended",
@@ -10889,7 +10916,7 @@ var POLL_WAKE_PATH_RULES = Object.freeze([
 ]);
 var POLL_SEND_AND_END_RULE = "`Send & End` ends the session. Its final feedback is still delivered once. After that response, polling stops, and the agent must not reopen the session uninvited.";
 var CODEX_POLL_WAKE_PATH_GUIDANCE = "Codex detected: completed background tasks may not resume Codex automatically, so keep the poll attached to the active turn.";
-var VERSION = "0.1.64";
+var VERSION = "0.1.66";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",
@@ -38,7 +38,8 @@
     "daisyui": "^5.5.19",
     "express": "^5.2.1",
     "open": "^10.2.0",
-    "parse5": "^8.0.1"
+    "parse5": "^8.0.1",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "lavish-axi",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "author": {
     "name": "Kun Chen",