@runtypelabs/persona 4.4.2 → 4.6.0

package/src/client.ts

@@ -954,11 +954,12 @@ export class AgentWidgetClient {
   public async processStream(
     body: ReadableStream<Uint8Array>,
     onEvent: SSEHandler,
-    assistantMessageId?: string
+    assistantMessageId?: string,
+    seedContent?: string
   ): Promise<void> {
     onEvent({ type: "status", status: "connected" });
     try {
-      await this.streamResponse(body, onEvent, assistantMessageId);
+      await this.streamResponse(body, onEvent, assistantMessageId, seedContent);
     } finally {
       onEvent({ type: "status", status: "idle" });
     }
@@ -1353,7 +1354,12 @@ export class AgentWidgetClient {
   private async streamResponse(
     body: ReadableStream<Uint8Array>,
     onEvent: SSEHandler,
-    assistantMessageId?: string
+    assistantMessageId?: string,
+    // Durable reconnect: seed the assistant accumulator with the text already
+    // shown before the drop, so replayed post-cursor deltas APPEND to it
+    // instead of a fresh stream clobbering it (the replay carries only
+    // `seq > after`, i.e. the new deltas, not the full text).
+    seedContent?: string
   ) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -1490,10 +1496,14 @@ export class AgentWidgetClient {
     const ensureAssistantMessage = () => {
       if (assistantMessage) return assistantMessage;
       let id: string;
+      let initialContent = "";
       const segment = currentTextBlockId;
       if (!assistantIdConsumed && baseAssistantId) {
         id = baseAssistantId;
         assistantIdConsumed = true;
+        // First (and only) time we reuse the caller-supplied id: this is the
+        // bubble a durable reconnect resumes into, so continue its text.
+        initialContent = seedContent ?? "";
       } else if (baseAssistantId && segment) {
         id = `${baseAssistantId}_${segment}`;
       } else {
@@ -1502,7 +1512,7 @@ export class AgentWidgetClient {
       assistantMessage = {
         id,
         role: "assistant",
-        content: "",
+        content: initialContent,
         createdAt: new Date().toISOString(),
         streaming: true,
         sequence: nextSequence()
@@ -2877,7 +2887,11 @@ export class AgentWidgetClient {
           pendingFlowRaw = "";
           lastSealedFlowBubble = null;
 
-          onEvent({ type: "status", status: "idle" });
+          // `terminal: true` marks this as a graceful finish (not a drop). The
+          // session uses it to distinguish the real end-of-turn from the plain
+          // `idle` the dispatch wrappers emit in their `finally` when a durable
+          // connection drops mid-stream (durable-reconnect drop detection).
+          onEvent({ type: "status", status: "idle", terminal: true });
         } else if (payloadType === "execution_error") {
           // Terminal failure. The non-terminal `error` is handled
           // separately (recoverable → warn).
@@ -3163,20 +3177,43 @@ export class AgentWidgetClient {
         const lines = event.split("\n");
         let eventType = "message";
         let data = "";
+        // Durable-reconnect cursor: the SSE `id:` line (the durable row seq).
+        // Only durable, resumable agent executions stamp these (e.g. Claude
+        // Managed agents, or any async/background run the backend persists and
+        // can replay); other streams carry no cursor. We emit a `cursor`
+        // event AFTER the frame is fully parsed and dispatched, so the session's
+        // `lastEventId` only advances past frames it has actually applied, so the
+        // happy path has no dupes against the server's `seq > after` replay.
+        let frameId: string | null = null;
 
         for (const line of lines) {
           if (line.startsWith("event:")) {
             eventType = line.replace("event:", "").trim();
           } else if (line.startsWith("data:")) {
             data += line.replace("data:", "").trim();
+          } else if (line.startsWith("id:")) {
+            frameId = line.slice(3).trim();
           }
         }
 
-        if (!data) continue;
+        const advanceCursor = () => {
+          if (frameId !== null && frameId !== "") {
+            onEvent({ type: "cursor", id: frameId });
+          }
+        };
+
+        // A frame with an `id:` but no `data:` (e.g. a bare keepalive line) is
+        // still a received durable row, so advance the cursor past it.
+        if (!data) {
+          advanceCursor();
+          continue;
+        }
         let payload: any;
         try {
           payload = JSON.parse(data);
         } catch (error) {
+          // Parse failure: the frame was NOT applied. Do NOT advance the cursor
+          // so a reconnect re-fetches this row.
           onEvent({
             type: "error",
             error:
@@ -3209,7 +3246,10 @@ export class AgentWidgetClient {
           if (assistantMessageRef.current && assistantMessageRef.current !== assistantMessage) {
             assistantMessage = assistantMessageRef.current;
           }
-          if (handled) continue; // Skip default handling if custom handler processed it
+          if (handled) {
+            advanceCursor();
+            continue; // Skip default handling if custom handler processed it
+          }
         }
 
         // The wire is the wire vocabulary; the handler consumes it
@@ -3217,6 +3257,7 @@ export class AgentWidgetClient {
         // drains straight through.
         seqReadyQueue.push({ payloadType, payload });
         drainReadyQueue();
+        advanceCursor();
       }
     }
 

package/src/defaults.ts

@@ -129,8 +129,16 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       label: "",
     },
     scrollBehavior: {
-      mode: "follow",
+      // ChatGPT-style default: pin the just-sent message near the top and let
+      // the reply stream into the space below. Restore the old "stick to the
+      // bottom" behavior with `mode: "follow"`.
+      mode: "anchor-top",
       anchorTopOffset: 16,
+      // Surface the unread count + "streaming below" hint while pinned, so the
+      // reader still sees activity arriving off-screen under the pinned turn.
+      // (Suppressed by default historically; opted on alongside the anchor-top
+      // default so the default UX keeps the affordance.)
+      showActivityWhilePinned: true,
     },
     toolCallDisplay: {
       collapsedMode: "tool-call",

package/src/generated/runtype-openapi-contract.ts

@@ -311,12 +311,15 @@ export type RuntypeExecutionStreamEvent = ({
   seq: number;
   type: "approval_complete";
 }) | ({
+  awaitReason?: string;
   awaitedAt?: string;
+  crawlId?: string;
   executionId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
   parameters?: Record<string, unknown>;
   seq: number;
+  stepId?: string;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;
@@ -406,13 +409,16 @@ export type RuntypeFlowSSEEvent = {
   type: "flow_error";
   upgradeUrl?: string;
 }) | ({
+  awaitReason?: string;
   awaitedAt: string;
+  crawlId?: string;
   executionId?: string;
   flowId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
   parameters?: Record<string, unknown>;
   seq?: number;
+  stepId?: string;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;

package/src/index-core.ts

@@ -263,6 +263,11 @@ export type {
   AgentWidgetStreamAnimationType,
   AgentWidgetStreamAnimationFeature,
   AgentWidgetStreamAnimationPlaceholder,
+  AgentWidgetScrollMode,
+  AgentWidgetScrollRestorePosition,
+  AgentWidgetScrollBehaviorFeature,
+  AgentWidgetScrollToBottomFeature,
+  AgentWidgetComponentRenderer,
 } from "./types";
 
 // Action system types: needed to type the `actionHandlers` / `actionParsers`

package/src/reconnect-wake.test.ts

@@ -0,0 +1,162 @@
+// @vitest-environment jsdom
+//
+// Wake-listener behavior for durable reconnect (`session-reconnect.ts`). These
+// need a DOM so the `visibilitychange` / `online` listeners actually attach, so
+// this file runs in jsdom (the sibling `reconnect.test.ts` is node-env, where
+// the `typeof document/window` guards skip the listeners entirely).
+//
+// The crux: `online` must short-circuit the backoff sleep even when the tab is
+// backgrounded, while `visibilitychange` must only wake on the show transition.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
+import { AgentWidgetMessage } from "./types";
+
+const enc = new TextEncoder();
+
+function sseStream(frames: string[]): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      for (const f of frames) controller.enqueue(enc.encode(f));
+      controller.close();
+    },
+  });
+}
+
+function frame(
+  id: number | null,
+  type: string,
+  data: Record<string, unknown> = {}
+): string {
+  const head = id !== null ? `id: ${id}\n` : "";
+  return `${head}event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`;
+}
+
+async function waitFor(pred: () => boolean, timeoutMs = 1500): Promise<void> {
+  const start = Date.now();
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    if (pred()) return;
+    if (Date.now() - start > timeoutMs) throw new Error("waitFor: timed out");
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+function setVisibility(state: "visible" | "hidden"): void {
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    get: () => state,
+  });
+}
+
+describe("AgentWidgetSession - reconnect wake listeners", () => {
+  let messages: AgentWidgetMessage[];
+  let status: AgentWidgetSessionStatus;
+  let reconnectPhases: string[];
+
+  const baseCallbacks = () => ({
+    onMessagesChanged: (m: AgentWidgetMessage[]) => {
+      messages = m;
+    },
+    onStatusChanged: (s: AgentWidgetSessionStatus) => {
+      status = s;
+    },
+    onStreamingChanged: () => {},
+    onError: () => {},
+    onReconnect: (ev: { phase: string }) => {
+      reconnectPhases.push(ev.phase);
+    },
+  });
+
+  const assistantText = () =>
+    messages.find((m) => m.role === "assistant" && !m.variant)?.content ?? "";
+
+  // A session that drops mid-stream, fails its first reconnect attempt (forcing
+  // a deliberately long backoff sleep), then succeeds on the second. A prompt
+  // 2nd attempt can therefore only mean a wake fired — never the 10s timer.
+  function dropThenResumeSession() {
+    const initial = sseStream([
+      frame(1, "text_delta", {
+        id: "text_0",
+        delta: "Hello",
+        executionId: "exec_1",
+      }),
+    ]);
+    const resume = sseStream([
+      frame(2, "text_delta", {
+        id: "text_0",
+        delta: " world",
+        executionId: "exec_1",
+      }),
+      frame(3, "execution_complete", { success: true, kind: "agent" }),
+    ]);
+    let calls = 0;
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: "http://x",
+        customFetch: async () => ({ ok: true, body: initial }) as any,
+        reconnectStream: async () => {
+          calls += 1;
+          if (calls === 1) return { ok: false } as any;
+          return { ok: true, body: resume } as any;
+        },
+        reconnect: { backoffMs: [10000], maxAttempts: 5 },
+      },
+      baseCallbacks()
+    );
+    return {
+      session,
+      getCalls: () => calls,
+    };
+  }
+
+  beforeEach(() => {
+    messages = [];
+    status = "idle";
+    reconnectPhases = [];
+    setVisibility("visible");
+  });
+
+  afterEach(() => {
+    setVisibility("visible");
+    vi.restoreAllMocks();
+  });
+
+  it("online wakes the backoff immediately even when the tab is backgrounded", async () => {
+    const { session, getCalls } = dropThenResumeSession();
+
+    await session.sendMessage("hi");
+    // Wait until the first reconnect attempt has failed and we're sleeping in
+    // the (10s) backoff before the second attempt.
+    await waitFor(() => status === "paused");
+    expect(getCalls()).toBe(1);
+
+    // Background the tab, then regain connectivity. The visibility guard must
+    // NOT suppress the `online` wake.
+    setVisibility("hidden");
+    window.dispatchEvent(new Event("online"));
+
+    // Without the fix this times out (the loop would wait the full 10s).
+    await waitFor(() => reconnectPhases.includes("resumed"));
+    expect(getCalls()).toBe(2);
+    expect(assistantText()).toBe("Hello world");
+    expect(status).toBe("idle");
+  });
+
+  it("visibilitychange wakes the backoff when the tab becomes visible", async () => {
+    const { session, getCalls } = dropThenResumeSession();
+
+    await session.sendMessage("hi");
+    await waitFor(() => status === "paused");
+    expect(getCalls()).toBe(1);
+
+    // Tab brought back to the foreground: the show transition should wake.
+    setVisibility("visible");
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    await waitFor(() => reconnectPhases.includes("resumed"));
+    expect(getCalls()).toBe(2);
+    expect(assistantText()).toBe("Hello world");
+    expect(status).toBe("idle");
+  });
+});