@helpai/elements 0.7.5 → 0.8.1

package/web-component.mjs

@@ -1226,6 +1226,17 @@ var AgentTransport = class {
     this.userContext = userContext;
     this.pageContext = pageContext;
   }
+  /**
+   * Seed the visitor + session identity from persistence BEFORE the first
+   * `startSession` resolves. A mount-time `resumeStream()` runs in parallel
+   * with `startSession`, so without this its envelope would carry no
+   * `sessionId` and the resume GET couldn't identify the thread. `startSession`
+   * later overwrites these with the server's authoritative ids (rebind-safe).
+   */
+  primeIdentity(visitorId, sessionId) {
+    if (visitorId) this.visitorId = visitorId;
+    if (sessionId) this.sessionId = sessionId;
+  }
   /** Build the per-request envelope from the current transport state. */
   envelope() {
     const out = {};
@@ -1309,9 +1320,10 @@ var AgentTransport = class {
       cursor: params.cursor
     });
     const res = await this.getJson(url.toString(), "listSessions");
-    log4.debug("listSessions \u2190", { count: res.sessions.length, nextCursor: res.nextCursor });
+    const sessions = res.sessions ?? [];
+    log4.debug("listSessions \u2190", { count: sessions.length, nextCursor: res.nextCursor });
     return {
-      sessions: res.sessions.map((session) => ({
+      sessions: sessions.map((session) => ({
         sessionId: session.sessionId,
         title: session.title,
         lastMessageAt: session.lastMessageAt,
@@ -1327,16 +1339,17 @@ var AgentTransport = class {
     url.searchParams.set("sessionId", sessionId);
     log4.debug("loadSession \u2192", { sessionId, visitorId: this.visitorId });
     const res = await this.getJson(url.toString(), "loadSession");
+    const messages = res.messages ?? [];
     log4.debug("loadSession \u2190", {
       sessionId: res.sessionId,
       canContinue: res.canContinue,
-      messageCount: res.messages.length,
+      messageCount: messages.length,
       hasSuggestions: !!res.suggestions
     });
     return {
       sessionId: res.sessionId,
-      canContinue: res.canContinue,
-      messages: res.messages,
+      canContinue: res.canContinue ?? true,
+      messages,
       agent: res.agent,
       suggestions: res.suggestions
     };
@@ -1370,8 +1383,9 @@ var AgentTransport = class {
     }
     log4.debug("listContent \u2192", query);
     const res = await this.getJson(url.toString(), "listContent");
-    log4.debug("listContent \u2190", { count: res.items.length, total: res.pagination?.total });
-    return res;
+    const items = res.items ?? [];
+    log4.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
+    return { ...res, items };
   }
   async saveUserPrefs(userPrefs) {
     log4.debug("saveUserPrefs \u2192", {
@@ -1404,12 +1418,62 @@ var AgentTransport = class {
     const cancel = () => this.cancelStream(ctrl, body.sessionId);
     return { iter, cancel };
   }
+  /**
+   * Re-attach to an in-flight reply on a cold page load / refresh.
+   *
+   * UNCONDITIONAL by design — the caller runs this in parallel with
+   * `startSession`, never gated on whether there are persisted messages. If
+   * the user refreshed while the assistant was still streaming, the
+   * `startSession` reply carries no messages (the turn isn't persisted until
+   * it finishes) and THIS is the channel that resumes the live reply. When
+   * nothing is in flight the server answers 204 and the handle yields nothing
+   * (the common case — no bubble is created).
+   *
+   * `cancel` only detaches the client (aborts the local read); unlike
+   * `sendMessage` it does NOT POST `/cancel-stream` — the reply may still be
+   * generating for another tab or about to be persisted, and a page-load
+   * resume must never tear that down.
+   */
+  resumeStream() {
+    const ctrl = new AbortController();
+    const seenIds = /* @__PURE__ */ new Set();
+    const iter = this.resumeStreamGen(ctrl, seenIds, true);
+    return { iter, cancel: () => ctrl.abort() };
+  }
   // ---- Stream orchestration ---------------------------------------------
   async *runStream(body, ctrl, seenIds) {
     if (yield* this.drain(this.openMessageStream(body, ctrl.signal), seenIds, ctrl)) return;
+    yield* this.resumeStreamGen(ctrl, seenIds, false);
+  }
+  /**
+   * Re-attach to an in-flight reply via GET /stream-resume, yielding the
+   * (deduped) continuation. Two callers:
+   *   - after a POST /stream-message drops mid-reply (`immediate=false` — back
+   *     off first, the reply may still be spinning up server-side);
+   *   - on a cold page load / refresh (`immediate=true` — hit it at once, in
+   *     parallel with start-session, so a reply that was streaming when the
+   *     user reloaded keeps flowing).
+   *
+   * The endpoint ALWAYS opens a 200 SSE stream (mirrors the AI SDK
+   * resumable-stream lib): it replays the in-flight reply from the buffer, or —
+   * when nothing is in flight (reply finished + the buffer was flushed, or
+   * nothing ever started) — closes an EMPTY stream. So "nothing to resume" is
+   * signalled by a segment that ends without a terminal chunk AND surfaced no
+   * NEW events — not by a status code. We stop gracefully there; the completed
+   * turn comes from the DB via start-session / list-messages.
+   *
+   * Returns (no throw) on a terminal chunk, an empty/no-new-events segment, or
+   * a 204 / non-OK (a backend that signals "nothing" by status, or lacks the
+   * endpoint). Retries only a segment that yielded new events but no finish — a
+   * real mid-reply drop. Throws only if every attempt kept yielding new events
+   * yet never finished: a genuinely stuck, incomplete reply.
+   */
+  async *resumeStreamGen(ctrl, seenIds, immediate) {
     for (let attempt = 1; attempt <= MAX_RESUME_ATTEMPTS && !ctrl.signal.aborted; attempt++) {
-      await sleep(RESUME_BACKOFF_MS * attempt, ctrl.signal);
-      if (ctrl.signal.aborted) return;
+      if (!immediate || attempt > 1) {
+        await sleep(RESUME_BACKOFF_MS * attempt, ctrl.signal);
+        if (ctrl.signal.aborted) return;
+      }
       let res;
       try {
         res = await this.fetchImpl(this.resumeUrl(seenIds.size), {
@@ -1427,7 +1491,12 @@ var AgentTransport = class {
         log4.debug("resume \u2192 no in-flight stream", { status: res.status });
         return;
       }
+      const before = seenIds.size;
       if (yield* this.drain(parseChatStream(res, ctrl.signal), seenIds, ctrl)) return;
+      if (seenIds.size === before) {
+        log4.debug("resume \u2192 stream closed with no new events; nothing to resume");
+        return;
+      }
     }
     if (ctrl.signal.aborted) return;
     throw new StreamError("stream incomplete after resume attempts", "server");
@@ -3779,7 +3848,7 @@ function ConversationList({ transport, strings, visitorId, onSelect, onNewChat }
     let cancelled = false;
     transport.listSessions({ visitorId }).then((res) => {
       if (cancelled) return;
-      setChats(res.sessions);
+      setChats(res.sessions ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -4670,7 +4739,7 @@ function HelpRoot({ transport, strings, config, nav, panelProps }) {
     setState("loading");
     transport.listContent({ tags, sortBy: "order", limit: 100 }).then((res) => {
       if (cancelled) return;
-      setItems(res.items);
+      setItems(res.items ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -4744,7 +4813,7 @@ function HomeRoot(props2) {
   useEffect12(() => {
     if (!config.showRecentMessages) return;
     let cancelled = false;
-    transport.listSessions({ limit: 1 }).then((res) => !cancelled && setRecent(res.sessions[0] ?? null)).catch((err) => !cancelled && log13.warn("listSessions (home) failed", { err }));
+    transport.listSessions({ limit: 1 }).then((res) => !cancelled && setRecent(res.sessions?.[0] ?? null)).catch((err) => !cancelled && log13.warn("listSessions (home) failed", { err }));
     return () => {
       cancelled = true;
     };
@@ -4752,7 +4821,7 @@ function HomeRoot(props2) {
   useEffect12(() => {
     if (!config.contentTags?.length) return;
     let cancelled = false;
-    transport.listContent({ tags: config.contentTags, limit: 6 }).then((res) => !cancelled && setContent(res.items)).catch((err) => !cancelled && log13.warn("listContent (home) failed", { err }));
+    transport.listContent({ tags: config.contentTags, limit: 6 }).then((res) => !cancelled && setContent(res.items ?? [])).catch((err) => !cancelled && log13.warn("listContent (home) failed", { err }));
     return () => {
       cancelled = true;
     };
@@ -4848,7 +4917,7 @@ function NewsRoot({ transport, strings, config, nav, panelProps }) {
     setState("loading");
     transport.listContent({ tags, sortBy: "publishedAt", sortOrder: "desc" }).then((res) => {
       if (cancelled) return;
-      setItems(res.items);
+      setItems(res.items ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -5461,10 +5530,11 @@ function App({ options, hostElement, bus }) {
       if (isResume) {
         setLoadingMessages(true);
         try {
-          const chat = res.messages ? { sessionId: persistedChatId, canContinue: res.canContinue ?? true, messages: res.messages } : await transport.loadSession(persistedChatId);
+          const chat = res.messages?.length ? { sessionId: persistedChatId, canContinue: res.canContinue ?? true, messages: res.messages } : await transport.loadSession(persistedChatId);
           if (isStale()) return;
-          messagesSig.value = chat.messages.map(fromWireMessage);
-          setCanSend(chat.canContinue);
+          const loaded = (chat.messages ?? []).map(fromWireMessage);
+          if (loaded.length) messagesSig.value = loaded;
+          setCanSend(chat.canContinue ?? true);
           setSuggestions(chat.suggestions ?? []);
         } catch (err) {
           if (isStale()) return;
@@ -5491,10 +5561,57 @@ function App({ options, hostElement, bus }) {
   useEffect17(() => {
     transport.setContext(options.userContext, toWirePageContext(options.pageContext));
   }, [transport, userSig, pageSig]);
+  const runResume = useCallback8(
+    async (handle) => {
+      let bubble = null;
+      try {
+        for await (const evt of handle.iter) {
+          if (!bubble) {
+            bubble = makeAssistantMessage();
+            reducer.attach(bubble);
+            messagesSig.value = [...messagesSig.value, bubble];
+            setStreaming(true);
+            setActiveCancel(() => handle.cancel);
+            log16.info("resumed in-flight reply on mount");
+          }
+          reducer.apply(evt.chunk);
+          if (evt.chunk.type === "finish" && evt.chunk.canContinue === false) setCanSend(false);
+        }
+        if (bubble) {
+          bubble.status = "complete";
+          feedback.play("messageReceived");
+          emitMessage(bus, options, "assistant", assistantText(bubble));
+        }
+      } catch (err) {
+        if (bubble) {
+          bubble.status = "error";
+          bubble.errorText = errorMessageFor(err, options.strings);
+          feedback.play("error");
+        }
+        log16.debug("mount resume ended without completing", { err });
+      } finally {
+        if (bubble) {
+          reducer.detach();
+          setStreaming(false);
+          setActiveCancel(null);
+          messagesSig.value = [...messagesSig.value];
+        }
+      }
+    },
+    [reducer, messagesSig, feedback, bus, options]
+  );
   useEffect17(() => {
     void runStartSession({ newConversation: false });
+    const persistedSession = sessionIdSig.value;
+    let resume = null;
+    if (persistedSession) {
+      transport.primeIdentity(visitorId, persistedSession);
+      resume = transport.resumeStream();
+      void runResume(resume);
+    }
     return () => {
       connectGenRef.current++;
+      resume?.cancel();
     };
   }, []);
   const lastUserSig = useRef8(userSig);