bunnyquery 1.9.6 → 1.9.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunnyquery",
-  "version": "1.9.6",
+  "version": "1.9.10",
   "description": "Embeddable BunnyQuery AI chat widget + its framework-agnostic chat engine",
   "main": "bunnyquery.js",
   "exports": {

package/src/engine/config.ts

@@ -15,6 +15,52 @@
 
 import { type AttachmentParser, registerAttachmentParser } from './attachment_parsers';
 
+/**
+ * One report about a turn that is streaming, as handed to `onLiveStreamUpdate`.
+ *
+ * Deliberately a flat snapshot rather than the SseParser itself: the hook is a
+ * VIEW seam, and handing a client the parser would invite it to drive the stream
+ * (feed it, end it, read the assembled body) behind the session's back.
+ */
+export interface LiveStreamUpdate {
+    /** Server item id of the turn, the same id its bubbles carry as _serverItemId. */
+    serverItemId: string;
+    /** History cache key (`projectId#platform`) the turn belongs to. A host that
+     *  renders several projects must ignore an update for a chat it is not showing. */
+    ownerKey: string;
+    /** 'start' on the first paint, 'update' on every later one, 'end' once the
+     *  stream is over and nothing more will be painted - whether because the turn
+     *  settled (its authoritative answer is about to replace the live text) or
+     *  because it was stopped. 'end' is only sent to a host that was told 'start'. */
+    phase: 'start' | 'update' | 'end';
+    /** Answer text so far, already trimmed to a safe reveal boundary: it never
+     *  ends inside a half-arrived link, fence or url. Empty on 'end'. */
+    text: string;
+    /** Extended-thinking text so far. Separate from `text` and never part of it. */
+    thinkingText: string;
+    /** Tools reached for, in order of appearance, duplicates kept. */
+    toolNames: string[];
+    /** A terminal event arrived. False on 'end' means the stream was cut. */
+    complete: boolean;
+    /** The terminal event that arrived meant the answer FINISHED rather than DIED:
+     *  false while running, false on a cut stream, and false when the stream ended
+     *  on a provider error. `complete` answers "is anything more coming?"; this one
+     *  answers "is this the whole answer?", and they differ on exactly the case
+     *  that costs text - an `error` frame is terminal and truncating at once. A host
+     *  drawing a "partial answer" affordance wants THIS one. Added after `complete`
+     *  and always present: a host that ignores it reads as it did before. */
+    answerComplete: boolean;
+    /** The stream ended in a provider error. */
+    errored: boolean;
+    /** How many chunks of this turn each of skapi's two transports carried FIRST:
+     *  `socket` for the websocket relay, `poll` for the chunk-table read. Both feed
+     *  the same sink by design, so a turn that streamed perfectly over the socket
+     *  and one that was polled the whole way are otherwise indistinguishable. A
+     *  host that does not care can ignore it; a host showing a live/degraded
+     *  indicator, or just logging which path it got, reads this. */
+    transport: { socket: number; poll: number };
+}
+
 export interface ChatEngineConfig {
     /** skapi.clientSecretRequest, bound to the consumer's skapi instance. */
     clientSecretRequest: (opts: any) => Promise<any>;
@@ -86,6 +132,116 @@ export interface ChatEngineConfig {
             queue?: string;
         };
     }) => void;
+    /**
+     * Opt in to LIVE STREAMING of chat turns.
+     *
+     * Off by default, and for the same shipping-order reason `windowedIndexing`
+     * is: THE BACKEND MUST SHIP FIRST. When on, every chat turn carries two
+     * `stream` flags (see requests.ts chatStreamWiring) and the polling row
+     * settles with a STATUS AND NO BODY, because the answer was the stream. On a
+     * region whose polling worker does not relay, that same request either has
+     * its unknown `since` cursor rejected or stores an SSE transcript where the
+     * readers expect a parsed document, and the turn reads back as an empty
+     * answer. So it stays off until the worker is deployed, then flips per
+     * environment.
+     *
+     * It also needs `clientSecretRequestFinalize` below: without it a streamed
+     * turn is never finalized, so its row keeps a status and no body forever and
+     * a later history load shows the question with an empty answer.
+     */
+    liveStreaming?: boolean;
+    /**
+     * Also push each relayed chunk over skapi's websocket, so text lands as it is
+     * relayed instead of on the next poll tick. Requires `liveStreaming`.
+     *
+     * SEPARATE FROM `liveStreaming` ON PURPOSE, and off unless a host asks. It is a
+     * pure accelerator with a safe fallback, so the reason is not risk to the chat, it
+     * is what it does to the HOST'S OWN realtime: skapi's joinRealtime REPLACES the
+     * connection's group rather than adding to it, so for the length of a turn this
+     * takes the room. The dashboard owns its skapi instance and uses realtime for
+     * nothing else, so it opts in. The embeddable widget is handed the EMBEDDER'S
+     * instance and cannot know what their app does with it, so it stays off there
+     * unless the embedder turns it on.
+     */
+    liveStreamingRealtime?: boolean;
+    /**
+     * skapi.clientSecretRequestFinalize, bound to the consumer's skapi instance.
+     * Stores the version of a streamed turn that history should keep (the engine
+     * sends the ASSEMBLED provider body, so history reads it exactly as it reads
+     * a buffered turn) and releases that request's chunks. Optional: a host
+     * without it can still stream, it just leaves the chunks and an empty row.
+     */
+    clientSecretRequestFinalize?: (
+        requestId: string,
+        data: any,
+        options: { url: string; method: string; service?: string; owner?: string },
+    ) => Promise<any>;
+    /**
+     * skapi.clientSecretRequestStream, bound to the consumer's skapi instance.
+     *
+     * THE SECOND HALF OF THE DURABILITY GUARANTEE, and without it a streamed turn
+     * is only as durable as the tab that started it. A streamed row settles with a
+     * status and NO body; the answer is stored as chunks until
+     * clientSecretRequestFinalize says what to keep. A row that settles while no
+     * poll is attached (the user closed the tab, a mobile browser discarded it,
+     * the device slept and the interval stopped) is therefore never finalized, and
+     * a later history load sees a terminal row with no body and used to emit no
+     * assistant bubble at all: the answer simply gone from the conversation, with
+     * every byte of it still sitting in the chunk table.
+     *
+     * This is the documented way back to it. Given the request id it fetches every
+     * chunk of an already-finished turn in one pass (paging internally on `more`)
+     * and delivers them in order through `onStream`, then resolves. The engine
+     * feeds those into a fresh SSE parser and treats the assembled body exactly as
+     * it treats a live one, including finalizing it, which stores the answer as
+     * ordinary history and releases the chunks, so each row is recovered at most
+     * once ever.
+     *
+     * Optional. Without it the engine still marks such turns (`_streamPending` on
+     * the bubble) but has no way to read them back, so a host that ignores this
+     * behaves as it does today.
+     *
+     * NOTE THAT THIS HOOK, NOT `liveStreaming`, IS WHAT ARMS RECOVERY. See
+     * streamRecoveryEnabled() below for why the two decisions are separate.
+     */
+    clientSecretRequestStream?: (
+        requestId: string,
+        options: {
+            url: string;
+            method: string;
+            onStream?: (chunk: string, seq: number) => void;
+            since?: number;
+            poll?: number;
+            service?: string;
+            owner?: string;
+        },
+    ) => Promise<any>;
+    /**
+     * Observation hook for a live-streaming turn, called at most once per paint
+     * (about once a second) plus once when the turn settles.
+     *
+     * The engine already paints the answer text into the pending bubble itself,
+     * so a host needs this ONLY for the affordances the engine deliberately does
+     * not decide the presentation of: a "thinking..." line, or a "querying sales
+     * table..." row drawn from the tools the model reached for before any answer
+     * text exists. Optional, and a host without it behaves exactly as today.
+     *
+     * Never throw from it: it is called on the paint path and a throw would cost
+     * the user the rest of their answer. The engine guards it anyway.
+     */
+    onLiveStreamUpdate?: (update: LiveStreamUpdate) => void;
+    /**
+     * Force the read-back of already-streamed turns OFF, even though the chunk
+     * reader is injected.
+     *
+     * There is no need to set it to turn recovery ON: injecting
+     * `clientSecretRequestStream` is what arms it (see streamRecoveryEnabled).
+     * This exists only as the way back out for a host that wants byte-for-byte the
+     * pre-recovery rendering of a terminal-but-empty row - no bubble, no marker, no
+     * chunk read - while keeping the reader available for its own use. Omit it and
+     * nothing changes.
+     */
+    streamRecovery?: boolean;
     /**
      * Single-item csr-poll point lookup (skapi.util.request('csr-poll', {id,
      * service, owner}, {auth:true})). For a RESOLVED item the backend returns
@@ -120,6 +276,93 @@ export function windowedIndexingEnabled(): boolean {
     return _config?.windowedIndexing === true;
 }
 
+/** True when the consumer has opted in to live streaming of chat turns. */
+export function liveStreamingRealtimeEnabled(): boolean {
+    return liveStreamingEnabled() && _config?.liveStreamingRealtime === true;
+}
+
+export function liveStreamingEnabled(): boolean {
+    return _config?.liveStreaming === true;
+}
+
+/**
+ * True when a streamed turn whose answer never reached its row can be READ BACK.
+ *
+ * IT ASKS FOR THE READER AND NOT FOR `liveStreaming`, AND THAT SPLIT IS THE WHOLE
+ * POINT. "Should NEW turns stream?" and "can an ALREADY streamed row be recovered?"
+ * are two different questions about two different sets of rows, and answering both
+ * with one flag strands the second set the moment the first answer changes.
+ *
+ * The failure, and it is not hypothetical - it is what turning the feature off
+ * does. A row streamed yesterday holds its answer in the chunk table and a status
+ * and no body on the row; only csr-finalize ever copies one onto it. Flip
+ * `liveStreaming` off today (an embedder drops the option, a dev rolls the flag
+ * back after a bad deploy, a client's skapiSupportsStreaming probe degrades the
+ * instance to buffered) and every one of those rows instantly becomes unmarked,
+ * unrecoverable and unreadable: the mapper emits no bubble for it, the recovery
+ * never looks at it, and its answer is unreachable with every byte of it still
+ * stored. Rolling a rendering flag back must not delete anybody's history.
+ *
+ * The reader is the honest test because it is the CAPABILITY the recovery needs.
+ * Without it the engine could mark such a turn and never fill it in, trading a
+ * missing bubble for a permanently empty one, which is strictly worse than the
+ * bug - so the marker is still only ever minted when something can act on it.
+ *
+ * The cost of asking the wider question is one wasted read, once, on a row that
+ * was terminal and empty for some reason other than streaming (a buffered turn
+ * whose body the worker never managed to spill). That read finds no chunks, the
+ * bubble is dropped, and the list looks exactly as it did before. Set
+ * `streamRecovery: false` to opt out of even that.
+ */
+export function streamRecoveryEnabled(): boolean {
+    if (_config?.streamRecovery === false) return false;
+    return typeof _config?.clientSecretRequestStream === 'function';
+}
+
+/**
+ * Does a given skapi INSTANCE support the streaming half of the protocol? Ask this
+ * before honouring a `liveStreaming: true` opt-in, and degrade to buffered when the
+ * answer is no.
+ *
+ * THE FAILURE THIS PREVENTS, and it is the one the SDK's own docs call quiet. A
+ * streamed turn carries TWO `stream` flags: skapi's (relay the destination's bytes
+ * into the chunk table) and the DESTINATION's own field inside `data`, which
+ * BunnyQuery is the party that sets, because skapi relays bytes and knows no
+ * vendor. clientSecretRequest validates its params against a schema and KEEPS ONLY
+ * THE KEYS IN THAT SCHEMA, so an skapi-js predating the feature does not reject
+ * `stream` - it silently DROPS it. What ships is then the exact split
+ * chatStreamWiring exists to make impossible: the destination is asked to answer in
+ * SSE frames, skapi waits and stores the whole transcript on the row, and
+ * extractClaudeText / extractOpenAIText read a wall of `data: {...}` lines where a
+ * document should be and find no answer at all. Nothing throws and nothing logs;
+ * the user gets an empty reply on every single turn.
+ *
+ * It lives in the ENGINE rather than in each client because the two clients are
+ * diffed against each other and this is precisely the kind of predicate that forks:
+ * the widget must ask it (init() takes the EMBEDDER's instance, and an embed page
+ * pins its own skapi-js version, so `liveStreaming: true` is a REQUEST and this is
+ * what grants it) and agent.vue must ask it too (its instance is the repo's own, so
+ * only a stale node_modules or an unbuilt skapi-js can fail it - which is exactly
+ * the state a dev flipping the constant is most likely to be in, and a silently
+ * empty chat is the worst possible way to find out).
+ *
+ * Probed by the two public METHODS rather than by a version string, for two
+ * reasons. They ship in the same change as the `stream` key (one feature: the
+ * relay, the finalize that stores what to keep, and the read-back), so an SDK
+ * missing them is exactly the SDK that would drop the flag. And they are not merely
+ * a proxy for the capability, they ARE half of it - the engine needs finalize to
+ * store a streamed answer onto its row and stream to read an unfinalized one back,
+ * and streaming without either leaves every answer in the chunk table with nothing
+ * able to fetch it. There is no cheap DIRECT probe of the schema: the only way to
+ * learn that `stream` was dropped is to send a real request and read an empty
+ * answer, which is the bug itself.
+ */
+export function skapiSupportsStreaming(sk: any): boolean {
+    return !!sk
+        && typeof sk.clientSecretRequestStream === 'function'
+        && typeof sk.clientSecretRequestFinalize === 'function';
+}
+
 /** Spread helper: `{ ...pollOpt() }` adds `poll` only when configured. */
 export function pollOpt(): { poll?: number } {
     const p = _config?.poll;

package/src/engine/errors.ts

@@ -20,7 +20,73 @@ function isTransientStatus(status: number): boolean {
 	return status === 408 || status === 425 || status === 429 || status >= 500;
 }
 
+/**
+ * True when a csr-poll answer is the STATUS ENVELOPE rather than a stored body.
+ *
+ * Duck-typed, because the engine does not import skapi-js and the SDK does not
+ * export its own copy. The rule is the SDK's (isPollEnvelope): a request that has
+ * a stored result hands that result back verbatim, every other state hands back
+ * `{ id, status, in_queue, ... }`. A finalized body is the caller's own content
+ * and can itself carry a `status` key (OpenAI's Responses object does), so the
+ * id/in_queue pair is demanded too: a provider body would have to reproduce all
+ * three to be mistaken for an envelope.
+ *
+ * It lives HERE, next to the error readers, rather than in session.ts, because
+ * both of the things that have to recognise an envelope (the settle that
+ * substitutes an assembled body for one, and the error readers below) must agree
+ * on what one is. It was written twice once; that is how the error readers came to
+ * look one level too shallow.
+ */
+export function isCsrStatusEnvelope(res: any): boolean {
+	return !!res && typeof res === 'object' && !Array.isArray(res) &&
+		typeof res.status === 'string' && typeof res.id === 'string' && ('in_queue' in res);
+}
+
+/**
+ * The real error payload inside a FAILED csr-poll status envelope, or undefined
+ * when `input` is not one.
+ *
+ * THE FAILURE THIS PREVENTS, verbatim from the wire. A buffered turn that fails
+ * polls back as the worker's failed payload itself:
+ *
+ *     { status_code: 401, body: { error: { type, message } }, truncated: false }
+ *
+ * ...which every predicate below reads correctly. A STREAMED turn that fails does
+ * not: the poller (client_secret_key_request_polling) cannot return the error
+ * early for a streamed row, because the chunks that arrived before the stream died
+ * have to come back in the same response, so it falls through and ships
+ *
+ *     { id, status: 'failed', queue_name, in_queue, stream, chunks, last_seq,
+ *       more, error: <the payload above> }
+ *
+ * The payload is one level deeper, and every predicate here looked at the top
+ * level: `response.error.message` is undefined on it, `response.status_code` is
+ * absent, and `response.status` is the string 'failed' rather than a number. So a
+ * wrong API key on a streamed turn read as "not an error, and no answer either",
+ * which the caller renders as "No text response received from AI provider": the
+ * one message that tells the user nothing.
+ *
+ * Unwrapping HERE, once, is what makes a streamed error and a buffered error take
+ * the same path through every reader below. Deliberately not recursive: the value
+ * inside an envelope is a provider payload, never another envelope, and a single
+ * unwrap cannot loop on a malformed one.
+ *
+ * A failed envelope with a NULL payload (the worker recorded no detail, or its
+ * spill could not be fetched) still yields an object, because the row's status is
+ * itself the fact: 'failed' with nothing attached must not read as a clean turn.
+ */
+export function csrEnvelopeError(input: any): any {
+	if (!isCsrStatusEnvelope(input)) return undefined;
+	// Only a failure carries one. 'resolved' means the body IS the answer (the
+	// settle substitutes it), and 'cancelled' is settled by its own predicate
+	// upstream, which must keep seeing the envelope it recognises.
+	if (input.status !== 'failed') return undefined;
+	return input.error != null ? input.error : { message: 'The AI provider request failed.' };
+}
+
 export function getErrorMessage(input: any): string {
+	var envErr = csrEnvelopeError(input);
+	if (envErr !== undefined) input = envErr;
 	if (!input) return 'Something went wrong.';
 	if (typeof input === 'string') return input;
 	if (input.error && input.error.message) return input.error.message;
@@ -48,7 +114,11 @@ export function getErrorMessage(input: any): string {
 }
 
 export function isErrorResponseBody(response: any): boolean {
-	if (!response || typeof response !== 'object') return false;
+	// A FAILED streamed row is an error however empty its payload turned out to
+	// be: the status is the fact. See csrEnvelopeError.
+	var envErr = csrEnvelopeError(response);
+	if (envErr !== undefined) response = envErr;
+	if (!response || typeof response !== 'object') return envErr !== undefined;
 	if (typeof response.status_code === 'number' && response.status_code >= 400) return true;
 	if (response.type === 'error') return true;
 	if (response.error && (response.error.message || response.error.type)) return true;
@@ -78,6 +148,11 @@ export function isErrorResponseBody(response: any): boolean {
 // retryable after a token refresh — so 401 (auth) and 429/5xx (transient) are
 // intentionally NOT treated as non-retryable here.
 export function isNonRetryableRequestError(input: any): boolean {
+	// Same one-level unwrap as the readers above: a streamed turn's failure is
+	// wrapped in its poll envelope, and a retry gate that cannot see the payload
+	// would re-send a request the provider has already rejected as malformed.
+	var envErr = csrEnvelopeError(input);
+	if (envErr !== undefined) input = envErr;
 	if (!input || typeof input !== 'object') return false;
 
 	var status = typeof input.status_code === 'number' ? input.status_code
@@ -118,6 +193,12 @@ export function isNonRetryableRequestError(input: any): boolean {
 }
 
 export function isAuthExpiredError(input: any): boolean {
+	// A streamed turn whose bearer expired fails exactly like a buffered one, one
+	// level deeper. Without this unwrap the refresh-and-resend gate never fires on
+	// the streaming path, so an expiry that costs a buffered turn nothing costs a
+	// streamed turn the whole answer.
+	var envErr = csrEnvelopeError(input);
+	if (envErr !== undefined) input = envErr;
 	if (!input) return false;
 	var blobs: string[] = [];
 	var push = function (v: any) { if (typeof v === 'string' && v) blobs.push(v); };
@@ -156,6 +237,11 @@ export function isAuthExpiredError(input: any): boolean {
  * reduced to by getErrorMessage, because the view usually only keeps the text.
  */
 export function isProviderApiKeyError(input: any): boolean {
+	// Same unwrap. A wrong API key on a streamed turn is the exact case CRITICAL 2
+	// was reported for: without this the "check the project's key" affordance never
+	// appears on the platform the user is actually streaming with.
+	var envErr = csrEnvelopeError(input);
+	if (envErr !== undefined) input = envErr;
 	if (!input) return false;
 	var blobs: string[] = [];
 	var push = function (v: any) { if (typeof v === 'string' && v) blobs.push(v); };

package/src/engine/history.ts

@@ -6,6 +6,7 @@
  */
 import { extractClaudeText, extractOpenAIText, INDEXING_COMPLETE_MARKER, EMPTY_INDEXING_REPLY, getChatHistory, bgIndexingQueueName } from './requests';
 import { isErrorResponseBody, getErrorMessage } from './errors';
+import { streamRecoveryEnabled } from './config';
 import { sanitizeAttachmentLinksForHistory } from './links';
 import type { ChatMessage } from './host';
 
@@ -702,8 +703,11 @@ export type MapHistoryOptions = {
 };
 
 export function mapHistoryListToMessages(list: any[], platform: 'claude' | 'openai', opts: MapHistoryOptions) {
-	var mapped: any[] = [], runningItemIds: string[] = [];
+	var mapped: any[] = [], runningItemIds: string[] = [], streamPendingItemIds: string[] = [];
 	var extractAssistantText = platform === 'openai' ? extractOpenAIText : extractClaudeText;
+	// See the `isStreamPending` block below. Read ONCE per call rather than per
+	// item: it is a config lookup, and the answer cannot change mid-list.
+	var canRecoverStreams = streamRecoveryEnabled();
 	var filtered = filterListByClearHorizon(list, opts.clearedAt);
 	filtered.slice().reverse().forEach(function (item) {
 		var requestBody = item && item.request_body;
@@ -727,6 +731,45 @@ export function mapHistoryListToMessages(list: any[], platform: 'claude' | 'open
 			? ((typeof item.response_text === 'string' ? item.response_text : '').trim())
 			: ((extractAssistantText(response) || '').trim() || ''));
 		var isErrorResponse = !isPending && (isFailed || (!isCompact && isErrorResponseBody(response)));
+		// AN ANSWER THAT IS UNKNOWN, NOT EMPTY.
+		//
+		// A STREAMED turn stores nothing on its row: the relay appends the
+		// destination's bytes to the chunk table and settles the row with a status
+		// and no body, and only csr-finalize ever copies an answer onto the row. So a
+		// row that is terminal, carries no body and carries no error is not a turn
+		// that answered nothing: it is a turn nobody finalized. That happens for one
+		// ordinary reason: the row settled while no poll was attached (the tab was
+		// closed, a mobile browser discarded it, the device slept and the interval
+		// stopped), so the client that would have finalized it was not there.
+		//
+		// Read as "empty" (which is what the `assistantText` guard further down did),
+		// such a row produces NO assistant bubble at all and the answer is simply gone
+		// from the conversation, with every byte of it still sitting in the chunk
+		// table, reachable through clientSecretRequestStream. So it is marked instead,
+		// and the two things that act on the mark are the merge (an unknown answer
+		// never overwrites a known one) and the recovery (an unknown answer is
+		// resolved by reading the chunks back). See ChatMessage._streamPending.
+		//
+		// Deliberately narrow, so nothing that is genuinely an empty turn is caught:
+		//   - only when this host streams AND can read chunks back (see
+		//     streamRecoveryEnabled); a host that does neither behaves exactly as it
+		//     does today, and one that cannot read them back would only trade a
+		//     missing bubble for a permanently empty one;
+		//   - never on the background queue. chatStreamWiring turns streaming OFF for
+		//     every bg-queue turn (an indexing pass must not stream, and an attachment
+		//     turn is left buffered on purpose), so a bg row with no body really did
+		//     answer nothing;
+		//   - never on a compact stub, whose body was withheld by the server rather
+		//     than never stored;
+		//   - 'resolved' only. A FAILED row already renders its error, which is the
+		//     authoritative account of the turn (and, once csrEnvelopeError is in
+		//     play, a truthful one). Its chunks are deliberately kept but not
+		//     rendered. See _finalizeStreamedTurn.
+		var isStreamPending = canRecoverStreams && !isCompact && !isPending && !isCancelledItem
+			&& !isErrorResponse && !item._isBgTask && !item._isOnBgQueue
+			&& item.status === 'resolved'
+			&& (item.response_body == null) && (item.error == null)
+			&& !assistantText;
 		// Record the completion marker, then STRIP it — both, and in that order.
 		// Recording gives the display layer a structured signal instead of a substring
 		// search over model prose. Stripping matches the live resolution path: without
@@ -810,6 +853,14 @@ export function mapHistoryListToMessages(list: any[], platform: 'claude' | 'open
 			if (serverItemId !== undefined) em._serverItemId = serverItemId;
 			if (replyTs !== undefined) em._ts = replyTs;
 			mapped.push(em);
+		} else if (isStreamPending) {
+			// The bubble stands for the turn so the merge has something to key on and
+			// the recovery has somewhere to write. Its content is UNKNOWN: empty here
+			// is the absence of an answer on the row, not the absence of an answer.
+			var sp: any = { role: 'assistant', content: '', _streamPending: true };
+			if (serverItemId !== undefined) { sp._serverItemId = serverItemId; streamPendingItemIds.push(serverItemId); }
+			if (replyTs !== undefined) sp._ts = replyTs;
+			mapped.push(sp);
 		// `|| reportedComplete`: a pass whose ENTIRE answer was the completion token
 		// strips down to an empty string, and the plain `assistantText` guard then
 		// emitted no bubble at all — while the live path emitted one. The run read as
@@ -837,7 +888,54 @@ export function mapHistoryListToMessages(list: any[], platform: 'claude' | 'open
 		var ownerKey = chatCacheKey(opts.projectId, platform, opts.userId);
 		for (var oi = 0; oi < mapped.length; oi++) mapped[oi]._ownerKey = ownerKey;
 	}
-	return { messages: mapped, runningItemIds: runningItemIds };
+	// `streamPendingItemIds` is additive: a consumer that only destructures
+	// { messages, runningItemIds } (agent.vue's own call site does) is unaffected.
+	// The engine drives recovery off the BUBBLES rather than this list (the merge
+	// runs between the two and can adopt a local answer onto one of them), so this
+	// is reporting, not the mechanism.
+	return { messages: mapped, runningItemIds: runningItemIds, streamPendingItemIds: streamPendingItemIds };
+}
+
+/**
+ * Let a LOCAL copy of a turn survive a page whose copy of it is
+ * AUTHORITATIVE-BUT-EMPTY. Mutates `incoming`; returns true when it took anything.
+ *
+ * THE FAILURE THIS PREVENTS. A streamed turn's row goes 'resolved' the moment the
+ * relay finishes, and its answer reaches the row only when csr-finalize stores it,
+ * one poll interval plus a round trip later. A first-page history refetch landing
+ * inside that window maps the row to a `_streamPending` bubble with no content, and
+ * the merge, which believes the server, throws away the local bubble holding the
+ * answer the reader is looking at. The window opens on EVERY streamed turn, and a
+ * refetch fires from visibilitychange, so it is not a corner case.
+ *
+ * The rule is the same one the recovery reads: an UNKNOWN answer never overwrites a
+ * KNOWN one. Where the local copy is still live (pending, or being painted into),
+ * its live-ness is adopted too: without it the merge would hand back a settled
+ * bubble the painter can no longer find (_liveTargetIndex wants isPending or
+ * _streaming) and that _turnAlreadyRendered would then read as already answered, so
+ * the settle would drop the real answer on the floor.
+ */
+export function adoptLocalAnswerIntoPage(incoming: ChatMessage, local: ChatMessage): boolean {
+	if (!incoming || !local || !incoming._streamPending) return false;
+	if (incoming.role !== 'assistant' || local.role !== 'assistant') return false;
+	var hasText = typeof local.content === 'string' && local.content.length > 0;
+	var isLive = !!(local.isPending || local._streaming);
+	if (!hasText && !isLive) return false;
+	if (hasText) {
+		incoming.content = local.content;
+		// The answer is on screen, so nothing has to be read back. Whether the row
+		// itself ever gets a stored body is the live path's business (its finalize is
+		// in flight); if that fails, the NEXT load meets an empty row again and
+		// recovers it then.
+		incoming._streamPending = false;
+	}
+	// Carried whatever the text says: these are what keep a still-running turn
+	// reachable by the painter and by the settle.
+	if (local._localId !== undefined) incoming._localId = local._localId;
+	if (local.isPending) incoming.isPending = true;
+	if (local.isPendingInProcess) incoming.isPendingInProcess = true;
+	if (local._streaming) incoming._streaming = true;
+	return true;
 }
 
 /* ---- rescuing in-flight bubbles across a first-page refetch ---------------
@@ -886,6 +984,19 @@ export function shouldRescueInFlightMessage(m: ChatMessage, ctx: RescueDecisionC
 	// it. Unconditional: applying the pending-assistant test here would delete the
 	// user's message mid-upload whenever some other turn happened to be in flight.
 	if (m._stageId) return true;
+	// A bubble being painted from a LIVE stream, before its dispatch has reported a
+	// server id. Same shape of reason as the staged bubble above: the page identifies
+	// turns by id, so nothing in it can stand for this one, and dropping it would
+	// leave the stream with no bubble to paint into (the painter finds its target by
+	// _serverItemId, and this bubble has none to be found by) - the turn would sit on
+	// "Thinking..." until it settled, with every relayed byte already spent.
+	//
+	// Gated on the missing id rather than on _streaming alone, and deliberately: once
+	// the id IS on the bubble, the tests below are right and the local copy really is
+	// redundant. The page carries the same turn as a pending placeholder with that id,
+	// the painter finds THAT one on its next paint (about a second later), and rescuing
+	// as well would put the same turn on screen twice.
+	if (m._streaming && !m._serverItemId) return true;
 	if (!m._serverItemId && ctx.pageHasPendingAssistant) return false;
 	// In flight by its own flags, id or no id. The immediate-send pair is stamped
 	// with its server id as soon as the dispatch reports one, and that id is there

package/src/engine/host.ts

@@ -130,6 +130,91 @@ export interface ChatMessage {
 	 *  still dimmed. Cleared (with _dimSending) by markStagedMessageReady the moment
 	 *  the queue drains, which is when the turn genuinely becomes "(In queue)". */
 	isAwaitingIndexing?: boolean;
+	/** PROTOCOL + PRESENTATIONAL: this bubble is being painted from a LIVE stream.
+	 *
+	 *  It sits alongside `isPending`, never instead of it. The bubble is still the
+	 *  turn's "Thinking..." placeholder as far as every queue mechanism is concerned
+	 *  (_ownThinkingIndex, resolveQueuedUserBubble, typewriteLatestReply and the
+	 *  stray-pending sweep all find their target by isPending), and clearing that flag
+	 *  to mean "it has text now" would strand the turn's real answer beside an orphan.
+	 *  What this adds is the one thing those mechanisms do not care about and the VIEW
+	 *  does: `content` is already worth rendering, so draw the text instead of the
+	 *  spinner.
+	 *
+	 *  Cleared the moment the turn settles, BEFORE the authoritative answer replaces
+	 *  the live text: from that instant the bubble is an ordinary reply being typed.
+	 *  The partially painted `content` is deliberately left in place across that clear,
+	 *  because it is what the typewriter resumes from instead of replaying from zero.
+	 *
+	 *  Also read by shouldRescueInFlightMessage: a streaming bubble that has no server
+	 *  id yet is unrepresentable in a freshly fetched page, so it must survive the
+	 *  merge or its stream is orphaned with nothing left to paint into. */
+	_streaming?: boolean;
+	/**
+	 * This turn's row is TERMINAL but carries no stored answer, because the answer
+	 * was streamed and nobody ever finalized it: the bytes are in the chunk store,
+	 * not on the row. The bubble's `content` is therefore UNKNOWN, not empty.
+	 *
+	 * That distinction is the whole of the fix for two bugs that looked unrelated.
+	 * A refetch landing in the window between the row going 'resolved' and finalize
+	 * storing the body used to ERASE the answer off the screen (the server copy has
+	 * no content, so the merge dropped the local bubble that did); and a turn that
+	 * settled while no poll was attached (closed tab, slept device) used to be
+	 * unrecoverable, because the mapper emitted no assistant bubble at all for a
+	 * terminal-but-empty row. Both are the same question, "what should the merge
+	 * believe when the server copy is authoritative but empty", and the answer is
+	 * this flag: an unknown answer NEVER overwrites a known one, and an unknown one
+	 * left over after the merge is resolved by reading the chunks back
+	 * (ChatSession.recoverStreamedAnswer).
+	 *
+	 * For a view it is a rendering hint and nothing more: a bubble carrying it with
+	 * empty content is being fetched, so draw whatever this client draws for a
+	 * loading answer. A host that ignores it renders an empty bubble for the second
+	 * or two the recovery takes, which is what it would have rendered anyway.
+	 *
+	 * WHEN IT COMES OFF, because that is the half that loses answers. It comes off
+	 * for a FACT about the turn and never for an event in the client: an answer was
+	 * recovered and written in, or the chunks were read and were genuinely empty (in
+	 * which case the empty bubble is removed as well, restoring the list the mapper
+	 * used to produce). It stays ON when the read FAILED, when the read was STOPPED,
+	 * and when a live turn settled having painted nothing - three states that say
+	 * nothing whatever about the turn, and in which the chunks are all still there.
+	 * A marker cleared on one of those is an answer nothing will ever go back for,
+	 * so a host may see the same bubble marked across several loads while the reads
+	 * keep failing; that is the recoverable state, not a stuck one.
+	 */
+	_streamPending?: boolean;
+	/**
+	 * IS ANYTHING ACTUALLY DRIVING THIS BUBBLE RIGHT NOW? The second half of
+	 * `_streamPending`, and the half a view cannot do without.
+	 *
+	 * `_streamPending` says the answer is elsewhere; it does NOT say somebody is on
+	 * their way to fetch it, and the two are different states that used to render
+	 * identically. Recovery is capped per history load (STREAM_RECOVERY_PER_LOAD),
+	 * so the third and later marked turns on a page are marked and nobody is reading
+	 * them; a read that FAILED leaves the marker on with the attempt forgotten, which
+	 * is also nobody. Both drew the same loader as a live turn, so a bubble could
+	 * spin for the rest of the session with nothing behind it - the one thing a
+	 * spinner must never do, because it is a promise that something is coming.
+	 *
+	 * Three states, and only the first of them may draw a spinner:
+	 *   'active'   a chunk read is in flight or queued for this turn. Something IS
+	 *              coming; the loader is honest.
+	 *   'failed'   the last read failed. Nothing is coming until somebody asks
+	 *              again, so the view owes the reader a way to ask.
+	 *   undefined  nothing has been tried, or the attempt is over. Same obligation.
+	 *
+	 * Written by the engine only, and never persisted anywhere: it describes THIS
+	 * session's fetching, not the turn. A fresh history page therefore arrives
+	 * without it, and _adoptLocalAnswers re-stamps the page's still-marked bubbles
+	 * from the session's own bookkeeping, so a reload during a read does not turn a
+	 * live loader into a button (and back a second later).
+	 *
+	 * Read it through streamRecoveryPhase(msg), never directly: the phase folds in
+	 * "does this bubble need the affordance at all", and both clients must not
+	 * answer that twice.
+	 */
+	_streamRecovery?: 'active' | 'failed';
 	_serverItemId?: string;
 	_localId?: string;
 	_cancelling?: boolean;