bunnyquery 1.8.1 → 1.8.3

package/dist/engine.d.mts

@@ -372,6 +372,102 @@ declare function buildBoundedChatMessages(options: BoundedChatOptions): {
     estimatedBudget: number;
 };
 
+/**
+ * How a text file the chat offers as a download is encoded and labelled, so that
+ * whatever opens it reads the characters correctly, in any language.
+ *
+ * When the model answers with a fenced ```name.ext block, the client turns that
+ * block into a Blob and an <a download>. We always write UTF-8, but several very
+ * common consumers do not assume UTF-8 when nothing in the file says so, and fall
+ * back to the reader's local ANSI codepage: CP949 in Korea, CP932 in Japan,
+ * CP936/CP950 in China and Taiwan, CP1251 for Cyrillic. The file is valid and
+ * every non-ASCII character still opens as mojibake.
+ *
+ * There is no single fix, because the way a file declares "this is UTF-8" is a
+ * property of the FORMAT:
+ *
+ *   - a spreadsheet (csv/tsv) and a Windows text editor read a BOM;
+ *   - HTML is opened from disk with no HTTP headers, so only an in-document
+ *     <meta charset> survives;
+ *   - XML carries its encoding in its declaration, and a WRONG declaration makes
+ *     a conforming parser fail outright;
+ *   - RTF is 7-bit, so non-ASCII has to be escaped into \uNNNN?;
+ *   - JSON, JSONL and YAML are UTF-8 by specification, and a BOM BREAKS them.
+ *
+ * Anything unrecognised is left byte-for-byte alone: an unknown extension is far
+ * more likely to be machine-parsed, where an uninvited BOM is a new bug, than to
+ * be opened by a legacy editor.
+ *
+ * MIRROR of skapi-mcp/download-encoding.js, which does the same job for files the
+ * server publishes (writeReport / exportRecordsToFile). A file the user gets from
+ * a fenced block and the same file published as a download must behave
+ * identically, so the two have to change together.
+ */
+declare const BOM = "\uFEFF";
+/** Files a spreadsheet or a Windows text editor opens directly. */
+declare const BOM_EXTS: Set<string>;
+/** Read from disk with no HTTP headers, so the declaration must be in the file. */
+declare const HTML_EXTS: Set<string>;
+declare const XML_EXTS: Set<string>;
+declare const RTF_EXTS: Set<string>;
+/** Content types by extension. Every text family carries an explicit charset. */
+declare const EXT_CONTENT_TYPES: Record<string, string>;
+type EncodingClass = 'bom' | 'html' | 'xml' | 'rtf' | 'none';
+declare function normalizeExt(ext: string | null | undefined): string;
+/** Extension of a filename, '' when it has none. */
+declare function extOf(filename: string | null | undefined): string;
+/** Which encoding declaration this format understands. */
+declare function encodingClassForExt(ext: string | null | undefined): EncodingClass;
+/** True when a file with this extension must be written BOM-first. */
+declare function needsBomForExt(ext: string | null | undefined): boolean;
+/**
+ * Content type to declare. Everything textual carries an explicit charset:
+ * without one the receiving end guesses, and it guesses the local codepage.
+ */
+declare function contentTypeForExt(ext: string | null | undefined, fallback?: string): string;
+declare function hasBom(text: string): boolean;
+declare const HTML_HEAD_WINDOW = 4096;
+/**
+ * Make an HTML document state its own encoding. Downloaded HTML is opened from
+ * disk, where the Content-Type we set no longer exists, so a document with no
+ * <meta charset> is decoded with the browser's locale default.
+ */
+declare function ensureHtmlCharset(text: string): string;
+/**
+ * Correct an XML declaration that names the wrong encoding.
+ *
+ * A MISSING declaration is left alone on purpose: XML with none is UTF-8 by
+ * specification, so every conforming parser already gets it right. A declaration
+ * naming EUC-KR over UTF-8 bytes, on the other hand, makes a parser fail outright.
+ */
+declare function ensureXmlEncoding(text: string): string;
+/** True when the body really is RTF rather than text merely named .rtf. */
+declare function looksLikeRtf(text: string): boolean;
+/**
+ * Escape every non-ASCII character into RTF's \uNNNN? form.
+ *
+ * RTF is 7-bit: a literal UTF-8 byte in the body is read through the codepage the
+ * header declares, which is how Korean, Japanese and Cyrillic RTF turns to
+ * mojibake in Word. \uNNNN? is codepage-independent.
+ *
+ * ASCII is never touched, which matters: backslashes and braces in an RTF body
+ * are control syntax, and "escaping" them would destroy the document. \u takes a
+ * SIGNED 16-bit value, so anything above 0x7FFF is emitted negative, and astral
+ * characters are emitted as their two surrogates.
+ */
+declare function escapeRtfNonAscii(text: string): string;
+/** Apply the format's encoding declaration to a whole document. */
+declare function applyEncodingDeclaration(text: string, ext: string | null | undefined): string;
+/**
+ * Everything a client needs to turn a fenced ```name.ext block into a download:
+ * the exact text to put in the Blob and the type to give it.
+ */
+declare function prepareDownloadText(filename: string, body: string): {
+    ext: string;
+    text: string;
+    contentType: string;
+};
+
 /**
  * Pure link/path helpers (no DOM, no marked). Moved verbatim from the chatbox.
  * `serviceId` is passed as a PARAMETER (the original read it from a global) so
@@ -721,7 +817,7 @@ type CallClaudeWithMcpParams = {
     onResponse?: (res: any) => void;
     onError?: (err: any) => void;
 };
-declare const POLL_INTERVAL = 1500;
+declare const POLL_INTERVAL = 3000;
 declare function callClaudeWithMcp({ prompt, messages, service, owner, userId, model, maxTokens, system, mcpServer, extractContent, fileUrls, }: CallClaudeWithMcpParams): Promise<any>;
 declare function callClaudeWithPublicMcp(prompt: string, service: string, owner: string, messages?: ClaudeMessage[], system?: string, model?: string, userId?: string, extractContent?: ExtractDirective[], fileUrls?: FileUrlDirective[], onResponse?: (res: any) => void, onError?: (err: any) => void): Promise<any>;
 declare function callOpenAIWithPublicMcp(prompt: string, service: string, owner: string, messages?: OpenAIMessage[], system?: string, model?: string, userId?: string, extractContent?: ExtractDirective[], fileUrls?: FileUrlDirective[], onResponse?: (res: any) => void, onError?: (err: any) => void): Promise<any>;
@@ -730,7 +826,17 @@ type AttachmentSaveInfo = {
     model?: string;
     service: string;
     owner: string;
-    userId?: string;
+    /**
+     * Queue base for this indexing pass: "<userId>-bg". REQUIRED, and it must be
+     * the SAME value the chat turn uses (ChatSession.dispatchComposedMessage's
+     * `id.userId || id.serviceId`) — the backend serialises requests that share a
+     * queue name and runs different ones IN PARALLEL, so a pass enqueued under a
+     * different base does not hold the chat back at all. It was optional once,
+     * defaulting to `service`; the chatbox omitted it, and its files were indexed
+     * on "<serviceId>-bg" while its question ran on "<userId>-bg" — the question
+     * was answered from a file nothing had read yet. Pass `userId || serviceId`.
+     */
+    userId: string;
     serviceName?: string;
     serviceDescription?: string;
     attachment: {
@@ -765,6 +871,14 @@ declare function extractOpenAIText(response: any): any;
 declare function listClaudeModels(service: string, owner: string): Promise<any>;
 declare function listOpenAIModels(service: string, owner: string): Promise<any>;
 declare const BG_INDEXING_QUEUE_SUFFIX = "-bg";
+/**
+ * The one place the background-indexing queue name is spelled out. The backend
+ * serialises requests sharing a queue name and runs different names in PARALLEL,
+ * so every indexing pass AND the chat turn that must wait behind them have to
+ * resolve to the identical string — see AttachmentSaveInfo.userId for what
+ * happens when they do not.
+ */
+declare function bgIndexingQueueName(userId?: string, service?: string): string;
 /**
  * True when a request belongs to the background-indexing queue.
  *
@@ -835,6 +949,11 @@ interface ChatIdentity {
 interface PinnedDispatchContext {
     identity: ChatIdentity;
     systemPrompt: string;
+    /** Id returned by stageOutgoingMessage. The turn's bubble is already on
+     *  screen (staged while its attachments upload), so dispatchComposedMessage
+     *  REPLACES that bubble in place instead of pushing a second one at the
+     *  bottom — the message keeps the position it was sent in. */
+    stageId?: string;
 }
 /**
  * The file a background-indexing bubble belongs to. Stamped on the REQUEST
@@ -868,6 +987,17 @@ interface ChatMessage {
     /** Set on background-indexing REQUEST bubbles only (see IndexingFileRef). */
     _indexFile?: IndexingFileRef;
     _useBgQueue?: boolean;
+    /** Local id of a turn STAGED at Send time while its attachments upload. The
+     *  bubble exists before any server request does, so it is never matched by
+     *  _serverItemId and is never promoted/cancelled by the queue machinery —
+     *  dispatchComposedMessage consumes it (pinned.stageId) when the turn is
+     *  finally sent. Staged bubbles are deliberately kept OUT of the history
+     *  cache: an unmount kills the upload that would resolve them, so a cached
+     *  copy would replay as a bubble that uploads forever. */
+    _stageId?: string;
+    /** True on a staged bubble while its files are still uploading (renders
+     *  "(Uploading files...)" instead of "(In queue)"). */
+    isUploadingAttachments?: boolean;
     _serverItemId?: string;
     _localId?: string;
     _cancelling?: boolean;
@@ -1142,7 +1272,21 @@ declare class ChatSession {
     private _pauseReasons;
     private _resuming;
     private _lidSeq;
+    private _stageSeq;
+    /** How many attachment-upload batches are running. uploadingAttachments is a
+     *  single flag but batches overlap (the composer stays live, so the user can
+     *  send a second one while the first uploads), and a nested finish must not
+     *  clear the flag out from under the batch still running. */
+    private _uploadBatches;
+    /** Indexing requests whose ack has not come back yet. Until it does the item
+     *  is not on the server's queue, so awaitIndexingDrained cannot see it — and
+     *  would read the gap between "pass N settled" and "pass N+1 accepted" as the
+     *  file being finished. */
+    private _indexDispatchesInFlight;
     constructor(host: ChatHost);
+    /** Wrap an indexing-request dispatch so awaitIndexingDrained counts it as
+     *  live work from the moment it is sent, not from the moment it is acked. */
+    trackIndexDispatch<T>(p: Promise<T>): Promise<T>;
     /**
      * Register a live poll so (a) a remount dedupes against it instead of stacking a
      * SECOND poll on the same item, and (b) pausePolling can stop it.
@@ -1204,6 +1348,68 @@ declare class ChatSession {
      */
     private _callProviderFor;
     dispatchAgentRequest(params: any): Promise<any>;
+    /**
+     * Put a turn on screen the INSTANT the user hits Send, before its attachments
+     * have finished uploading. Uploads run in the background now (the composer is
+     * cleared and stays usable), so without a staged bubble the message would
+     * appear only once its files were up — below anything the user sent in the
+     * meantime, in an order that never matches what they typed.
+     *
+     * Staged bubbles carry _useBgQueue because that is where a turn with
+     * attachments ultimately dispatches (behind its own indexing tasks). That flag
+     * is also what keeps promoteNextQueuedToRunning / resolveQueuedUserBubble off
+     * them: those advance the SERVER queue, and a staged turn has no server
+     * request behind it yet.
+     *
+     * Returns the id to hand back as PinnedDispatchContext.stageId at dispatch.
+     */
+    stageOutgoingMessage(displayText: string): string;
+    private _stageIndex;
+    /**
+     * Where a staged turn belongs once it is finally sent: BELOW every indexing
+     * row, because that is the order it ran in and the order the server history
+     * will report on the next load (its request id is newer than every pass it
+     * waited for). While its files were uploading it sat above them — the rows
+     * are injected as each file's pass starts, after the bubble was staged.
+     *
+     * Returns the index to insert at, or -1 to leave the turn where it is. Never
+     * moves a turn UP: a bubble that already sits below the indexing rows (or a
+     * chat with no indexing at all) must not jump backwards over anything.
+     */
+    private _settledStagePosition;
+    /** The staged turn's files are up; it is now just waiting its place in the
+     *  queue. Drops the "(Uploading files...)" note back to "(In queue)". */
+    markStagedMessageQueued(stageId: string): void;
+    /**
+     * Resolves once this project's background-indexing queue has nothing left to
+     * run, so a chat enqueued right after it is genuinely last.
+     *
+     * Sending the chat as soon as the uploads finish is not enough, which is the
+     * whole reason this exists: indexing a file is a CHAIN, and each pass is only
+     * enqueued once the previous one lands (the client mints CONTINUE passes for
+     * text/grid files, the worker mints them for PDFs and windowed reads). Every
+     * one of those passes therefore queues up BEHIND a chat sent at upload time,
+     * and the model answers from a file it has only partly read.
+     *
+     * The queue is read from the server's status index rather than from
+     * bgTaskQueue: that mirror holds only what this client dispatched or adopted,
+     * and it stops being maintained once the view unmounts. An empty answer has to
+     * repeat before it is believed — see INDEXING_DRAIN_IDLE_LOOKS — and a look
+     * that fails counts as busy, so a dropped request delays the turn instead of
+     * releasing it early.
+     *
+     * Reads the identity PINNED at Send time, never a live one: the user may be in
+     * another project by now, and this must keep asking about the one they sent
+     * from.
+     */
+    awaitIndexingDrained(identity: ChatIdentity): Promise<'drained' | 'timedout' | 'skipped'>;
+    /**
+     * Abandon a staged turn — its uploads failed outright, so nothing will be
+     * dispatched. The bubble stays (the user's text is not silently thrown away)
+     * but settles into a plain, non-pending message; the caller reports the
+     * failure separately.
+     */
+    settleStagedMessage(stageId: string): void;
     dispatchComposedMessage(composed: string, useBgQueue?: boolean, composedForLlm?: string, extractContent?: any, fileUrls?: any, pinned?: PinnedDispatchContext): void;
     promoteNextBgQueuedToRunning(): void;
     promoteNextQueuedToRunning(): void;
@@ -1327,7 +1533,7 @@ declare class ChatSession {
         url: string;
         storagePath: string;
     }>>;
-    uploadPendingAttachments(): Promise<Array<{
+    uploadPendingAttachments(batchId?: string): Promise<Array<{
         name: string;
         url: string;
         storagePath?: string;
@@ -1336,4 +1542,4 @@ declare class ChatSession {
     bumpGate(): void;
 }
 
-export { type AiAgentPlatform, type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, type BgTaskEntry, type BoundedChatOptions, type BuildDisplayListOptions, type BuildIndexingUserMessageOptions, CLAUDE_INPUT_CAP_RATIO, CLAUDE_PER_REQUEST_INPUT_CAP, CONTEXT_WINDOW_BY_MODEL, CONTEXT_WINDOW_DEFAULT, type CallClaudeWithMcpParams, type ChatEngineConfig, type ChatHost, type ChatIdentity, type ChatMessage, ChatSession, type ChatState, type ChatSystemPromptParams, type ClaudeMcpServerRequest, type ClaudeMcpToolConfig, type ClaudeMessage, type ClaudeRole, type ComposedUserMessage, DEFAULT_CLAUDE_MODEL, DEFAULT_OPENAI_MODEL, type DisplayEntry, EXPIRED_ATTACHMENT_URL_HOST, EXPIRED_ATTACHMENT_URL_ORIGIN, EXPIRED_LINK_REFRESH_EXPIRES_SECONDS, type ExtractDirective, type FillHistoryViewportOptions, HISTORY_BUDGET_RATIO, HISTORY_FILL_SLACK_PX, HISTORY_TOKEN_BUDGET, type IndexingAttachmentInfo, type IndexingFileRef, type IndexingGroup, type IndexingGroupStatus, type IndexingRequestRef, type IndexingSystemPromptParams, type InlineLinkContext, type InlineLinkPart, LINK_LABEL_MAX_DISPLAY_CHARS, LINK_REFRESH_WINDOW_MS, MAX_HISTORY_FILL_PAGES, MAX_HISTORY_MESSAGES, MAX_PARSED_CONTENT_CHARS, MCP_NAME, MIN_INPUT_TOKEN_BUDGET, type MapHistoryOptions, OUTPUT_TOKEN_RESERVE, type OpenAIMessage, POLL_INTERVAL, type ParsedAiAgent, type PinnedDispatchContext, RENDER_FROM_TOKEN, TOOL_AND_RESPONSE_BUFFER, buildAiAgentValue, buildBoundedChatMessages, buildChatDisplayList, buildChatSystemPrompt, buildDisplayExpiredAttachmentHref, buildIndexingContinueMessage, buildIndexingRenderContinueTemplate, buildIndexingRenderMessage, buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingWindowMessage, callClaudeWithMcp, callClaudeWithPublicMcp, callOpenAIWithPublicMcp, chatEngineConfig, classifyInlineLink, clearAttachmentParsers, composeUserMessage, configureChatEngine, createHistoryFiller, createInlineLinkRegex, encodePathSegments, estimateMessageTokens, estimateTextTokens, extractClaudeText, extractLastUserTextFromRequest, extractOpenAIText, extractRemotePathFromAttachmentHref, fillHistoryViewport, filterListByClearHorizon, findAttachmentParser, formatChatTimestamp, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, getProjectContextWindow, groupAttachmentFailures, isAuthExpiredError, isBgIndexingQueue, isErrorResponseBody, isHttpUrlLike, isIndexingRequestText, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, makeExtractPlaceholder, mapHistoryListToMessages, normalizeAttachmentPathCandidate, normalizeTextContent, normalizeTrailingInlineToken, notifyAgentSaveAttachment, parseAiAgentValue, parseAttachmentContent, parseIndexingLabel, parseIndexingRequestText, readExpiredAttachmentHref, registerAttachmentParser, registerModelContextWindows, repairUrlEntities, repairUrlWhitespace, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, setProjectContextWindow, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay, wallClockNow };
+export { type AiAgentPlatform, type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, BOM, BOM_EXTS, type BgTaskEntry, type BoundedChatOptions, type BuildDisplayListOptions, type BuildIndexingUserMessageOptions, CLAUDE_INPUT_CAP_RATIO, CLAUDE_PER_REQUEST_INPUT_CAP, CONTEXT_WINDOW_BY_MODEL, CONTEXT_WINDOW_DEFAULT, type CallClaudeWithMcpParams, type ChatEngineConfig, type ChatHost, type ChatIdentity, type ChatMessage, ChatSession, type ChatState, type ChatSystemPromptParams, type ClaudeMcpServerRequest, type ClaudeMcpToolConfig, type ClaudeMessage, type ClaudeRole, type ComposedUserMessage, DEFAULT_CLAUDE_MODEL, DEFAULT_OPENAI_MODEL, type DisplayEntry, EXPIRED_ATTACHMENT_URL_HOST, EXPIRED_ATTACHMENT_URL_ORIGIN, EXPIRED_LINK_REFRESH_EXPIRES_SECONDS, EXT_CONTENT_TYPES, type EncodingClass, type ExtractDirective, type FillHistoryViewportOptions, HISTORY_BUDGET_RATIO, HISTORY_FILL_SLACK_PX, HISTORY_TOKEN_BUDGET, HTML_EXTS, HTML_HEAD_WINDOW, type IndexingAttachmentInfo, type IndexingFileRef, type IndexingGroup, type IndexingGroupStatus, type IndexingRequestRef, type IndexingSystemPromptParams, type InlineLinkContext, type InlineLinkPart, LINK_LABEL_MAX_DISPLAY_CHARS, LINK_REFRESH_WINDOW_MS, MAX_HISTORY_FILL_PAGES, MAX_HISTORY_MESSAGES, MAX_PARSED_CONTENT_CHARS, MCP_NAME, MIN_INPUT_TOKEN_BUDGET, type MapHistoryOptions, OUTPUT_TOKEN_RESERVE, type OpenAIMessage, POLL_INTERVAL, type ParsedAiAgent, type PinnedDispatchContext, RENDER_FROM_TOKEN, RTF_EXTS, TOOL_AND_RESPONSE_BUFFER, XML_EXTS, applyEncodingDeclaration, bgIndexingQueueName, buildAiAgentValue, buildBoundedChatMessages, buildChatDisplayList, buildChatSystemPrompt, buildDisplayExpiredAttachmentHref, buildIndexingContinueMessage, buildIndexingRenderContinueTemplate, buildIndexingRenderMessage, buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingWindowMessage, callClaudeWithMcp, callClaudeWithPublicMcp, callOpenAIWithPublicMcp, chatEngineConfig, classifyInlineLink, clearAttachmentParsers, composeUserMessage, configureChatEngine, contentTypeForExt, createHistoryFiller, createInlineLinkRegex, encodePathSegments, encodingClassForExt, ensureHtmlCharset, ensureXmlEncoding, escapeRtfNonAscii, estimateMessageTokens, estimateTextTokens, extOf, extractClaudeText, extractLastUserTextFromRequest, extractOpenAIText, extractRemotePathFromAttachmentHref, fillHistoryViewport, filterListByClearHorizon, findAttachmentParser, formatChatTimestamp, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, getProjectContextWindow, groupAttachmentFailures, hasBom, isAuthExpiredError, isBgIndexingQueue, isErrorResponseBody, isHttpUrlLike, isIndexingRequestText, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, looksLikeRtf, makeExtractPlaceholder, mapHistoryListToMessages, needsBomForExt, normalizeAttachmentPathCandidate, normalizeExt, normalizeTextContent, normalizeTrailingInlineToken, notifyAgentSaveAttachment, parseAiAgentValue, parseAttachmentContent, parseIndexingLabel, parseIndexingRequestText, prepareDownloadText, readExpiredAttachmentHref, registerAttachmentParser, registerModelContextWindows, repairUrlEntities, repairUrlWhitespace, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, setProjectContextWindow, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay, wallClockNow };

package/dist/engine.d.ts

@@ -372,6 +372,102 @@ declare function buildBoundedChatMessages(options: BoundedChatOptions): {
     estimatedBudget: number;
 };
 
+/**
+ * How a text file the chat offers as a download is encoded and labelled, so that
+ * whatever opens it reads the characters correctly, in any language.
+ *
+ * When the model answers with a fenced ```name.ext block, the client turns that
+ * block into a Blob and an <a download>. We always write UTF-8, but several very
+ * common consumers do not assume UTF-8 when nothing in the file says so, and fall
+ * back to the reader's local ANSI codepage: CP949 in Korea, CP932 in Japan,
+ * CP936/CP950 in China and Taiwan, CP1251 for Cyrillic. The file is valid and
+ * every non-ASCII character still opens as mojibake.
+ *
+ * There is no single fix, because the way a file declares "this is UTF-8" is a
+ * property of the FORMAT:
+ *
+ *   - a spreadsheet (csv/tsv) and a Windows text editor read a BOM;
+ *   - HTML is opened from disk with no HTTP headers, so only an in-document
+ *     <meta charset> survives;
+ *   - XML carries its encoding in its declaration, and a WRONG declaration makes
+ *     a conforming parser fail outright;
+ *   - RTF is 7-bit, so non-ASCII has to be escaped into \uNNNN?;
+ *   - JSON, JSONL and YAML are UTF-8 by specification, and a BOM BREAKS them.
+ *
+ * Anything unrecognised is left byte-for-byte alone: an unknown extension is far
+ * more likely to be machine-parsed, where an uninvited BOM is a new bug, than to
+ * be opened by a legacy editor.
+ *
+ * MIRROR of skapi-mcp/download-encoding.js, which does the same job for files the
+ * server publishes (writeReport / exportRecordsToFile). A file the user gets from
+ * a fenced block and the same file published as a download must behave
+ * identically, so the two have to change together.
+ */
+declare const BOM = "\uFEFF";
+/** Files a spreadsheet or a Windows text editor opens directly. */
+declare const BOM_EXTS: Set<string>;
+/** Read from disk with no HTTP headers, so the declaration must be in the file. */
+declare const HTML_EXTS: Set<string>;
+declare const XML_EXTS: Set<string>;
+declare const RTF_EXTS: Set<string>;
+/** Content types by extension. Every text family carries an explicit charset. */
+declare const EXT_CONTENT_TYPES: Record<string, string>;
+type EncodingClass = 'bom' | 'html' | 'xml' | 'rtf' | 'none';
+declare function normalizeExt(ext: string | null | undefined): string;
+/** Extension of a filename, '' when it has none. */
+declare function extOf(filename: string | null | undefined): string;
+/** Which encoding declaration this format understands. */
+declare function encodingClassForExt(ext: string | null | undefined): EncodingClass;
+/** True when a file with this extension must be written BOM-first. */
+declare function needsBomForExt(ext: string | null | undefined): boolean;
+/**
+ * Content type to declare. Everything textual carries an explicit charset:
+ * without one the receiving end guesses, and it guesses the local codepage.
+ */
+declare function contentTypeForExt(ext: string | null | undefined, fallback?: string): string;
+declare function hasBom(text: string): boolean;
+declare const HTML_HEAD_WINDOW = 4096;
+/**
+ * Make an HTML document state its own encoding. Downloaded HTML is opened from
+ * disk, where the Content-Type we set no longer exists, so a document with no
+ * <meta charset> is decoded with the browser's locale default.
+ */
+declare function ensureHtmlCharset(text: string): string;
+/**
+ * Correct an XML declaration that names the wrong encoding.
+ *
+ * A MISSING declaration is left alone on purpose: XML with none is UTF-8 by
+ * specification, so every conforming parser already gets it right. A declaration
+ * naming EUC-KR over UTF-8 bytes, on the other hand, makes a parser fail outright.
+ */
+declare function ensureXmlEncoding(text: string): string;
+/** True when the body really is RTF rather than text merely named .rtf. */
+declare function looksLikeRtf(text: string): boolean;
+/**
+ * Escape every non-ASCII character into RTF's \uNNNN? form.
+ *
+ * RTF is 7-bit: a literal UTF-8 byte in the body is read through the codepage the
+ * header declares, which is how Korean, Japanese and Cyrillic RTF turns to
+ * mojibake in Word. \uNNNN? is codepage-independent.
+ *
+ * ASCII is never touched, which matters: backslashes and braces in an RTF body
+ * are control syntax, and "escaping" them would destroy the document. \u takes a
+ * SIGNED 16-bit value, so anything above 0x7FFF is emitted negative, and astral
+ * characters are emitted as their two surrogates.
+ */
+declare function escapeRtfNonAscii(text: string): string;
+/** Apply the format's encoding declaration to a whole document. */
+declare function applyEncodingDeclaration(text: string, ext: string | null | undefined): string;
+/**
+ * Everything a client needs to turn a fenced ```name.ext block into a download:
+ * the exact text to put in the Blob and the type to give it.
+ */
+declare function prepareDownloadText(filename: string, body: string): {
+    ext: string;
+    text: string;
+    contentType: string;
+};
+
 /**
  * Pure link/path helpers (no DOM, no marked). Moved verbatim from the chatbox.
  * `serviceId` is passed as a PARAMETER (the original read it from a global) so
@@ -721,7 +817,7 @@ type CallClaudeWithMcpParams = {
     onResponse?: (res: any) => void;
     onError?: (err: any) => void;
 };
-declare const POLL_INTERVAL = 1500;
+declare const POLL_INTERVAL = 3000;
 declare function callClaudeWithMcp({ prompt, messages, service, owner, userId, model, maxTokens, system, mcpServer, extractContent, fileUrls, }: CallClaudeWithMcpParams): Promise<any>;
 declare function callClaudeWithPublicMcp(prompt: string, service: string, owner: string, messages?: ClaudeMessage[], system?: string, model?: string, userId?: string, extractContent?: ExtractDirective[], fileUrls?: FileUrlDirective[], onResponse?: (res: any) => void, onError?: (err: any) => void): Promise<any>;
 declare function callOpenAIWithPublicMcp(prompt: string, service: string, owner: string, messages?: OpenAIMessage[], system?: string, model?: string, userId?: string, extractContent?: ExtractDirective[], fileUrls?: FileUrlDirective[], onResponse?: (res: any) => void, onError?: (err: any) => void): Promise<any>;
@@ -730,7 +826,17 @@ type AttachmentSaveInfo = {
     model?: string;
     service: string;
     owner: string;
-    userId?: string;
+    /**
+     * Queue base for this indexing pass: "<userId>-bg". REQUIRED, and it must be
+     * the SAME value the chat turn uses (ChatSession.dispatchComposedMessage's
+     * `id.userId || id.serviceId`) — the backend serialises requests that share a
+     * queue name and runs different ones IN PARALLEL, so a pass enqueued under a
+     * different base does not hold the chat back at all. It was optional once,
+     * defaulting to `service`; the chatbox omitted it, and its files were indexed
+     * on "<serviceId>-bg" while its question ran on "<userId>-bg" — the question
+     * was answered from a file nothing had read yet. Pass `userId || serviceId`.
+     */
+    userId: string;
     serviceName?: string;
     serviceDescription?: string;
     attachment: {
@@ -765,6 +871,14 @@ declare function extractOpenAIText(response: any): any;
 declare function listClaudeModels(service: string, owner: string): Promise<any>;
 declare function listOpenAIModels(service: string, owner: string): Promise<any>;
 declare const BG_INDEXING_QUEUE_SUFFIX = "-bg";
+/**
+ * The one place the background-indexing queue name is spelled out. The backend
+ * serialises requests sharing a queue name and runs different names in PARALLEL,
+ * so every indexing pass AND the chat turn that must wait behind them have to
+ * resolve to the identical string — see AttachmentSaveInfo.userId for what
+ * happens when they do not.
+ */
+declare function bgIndexingQueueName(userId?: string, service?: string): string;
 /**
  * True when a request belongs to the background-indexing queue.
  *
@@ -835,6 +949,11 @@ interface ChatIdentity {
 interface PinnedDispatchContext {
     identity: ChatIdentity;
     systemPrompt: string;
+    /** Id returned by stageOutgoingMessage. The turn's bubble is already on
+     *  screen (staged while its attachments upload), so dispatchComposedMessage
+     *  REPLACES that bubble in place instead of pushing a second one at the
+     *  bottom — the message keeps the position it was sent in. */
+    stageId?: string;
 }
 /**
  * The file a background-indexing bubble belongs to. Stamped on the REQUEST
@@ -868,6 +987,17 @@ interface ChatMessage {
     /** Set on background-indexing REQUEST bubbles only (see IndexingFileRef). */
     _indexFile?: IndexingFileRef;
     _useBgQueue?: boolean;
+    /** Local id of a turn STAGED at Send time while its attachments upload. The
+     *  bubble exists before any server request does, so it is never matched by
+     *  _serverItemId and is never promoted/cancelled by the queue machinery —
+     *  dispatchComposedMessage consumes it (pinned.stageId) when the turn is
+     *  finally sent. Staged bubbles are deliberately kept OUT of the history
+     *  cache: an unmount kills the upload that would resolve them, so a cached
+     *  copy would replay as a bubble that uploads forever. */
+    _stageId?: string;
+    /** True on a staged bubble while its files are still uploading (renders
+     *  "(Uploading files...)" instead of "(In queue)"). */
+    isUploadingAttachments?: boolean;
     _serverItemId?: string;
     _localId?: string;
     _cancelling?: boolean;
@@ -1142,7 +1272,21 @@ declare class ChatSession {
     private _pauseReasons;
     private _resuming;
     private _lidSeq;
+    private _stageSeq;
+    /** How many attachment-upload batches are running. uploadingAttachments is a
+     *  single flag but batches overlap (the composer stays live, so the user can
+     *  send a second one while the first uploads), and a nested finish must not
+     *  clear the flag out from under the batch still running. */
+    private _uploadBatches;
+    /** Indexing requests whose ack has not come back yet. Until it does the item
+     *  is not on the server's queue, so awaitIndexingDrained cannot see it — and
+     *  would read the gap between "pass N settled" and "pass N+1 accepted" as the
+     *  file being finished. */
+    private _indexDispatchesInFlight;
     constructor(host: ChatHost);
+    /** Wrap an indexing-request dispatch so awaitIndexingDrained counts it as
+     *  live work from the moment it is sent, not from the moment it is acked. */
+    trackIndexDispatch<T>(p: Promise<T>): Promise<T>;
     /**
      * Register a live poll so (a) a remount dedupes against it instead of stacking a
      * SECOND poll on the same item, and (b) pausePolling can stop it.
@@ -1204,6 +1348,68 @@ declare class ChatSession {
      */
     private _callProviderFor;
     dispatchAgentRequest(params: any): Promise<any>;
+    /**
+     * Put a turn on screen the INSTANT the user hits Send, before its attachments
+     * have finished uploading. Uploads run in the background now (the composer is
+     * cleared and stays usable), so without a staged bubble the message would
+     * appear only once its files were up — below anything the user sent in the
+     * meantime, in an order that never matches what they typed.
+     *
+     * Staged bubbles carry _useBgQueue because that is where a turn with
+     * attachments ultimately dispatches (behind its own indexing tasks). That flag
+     * is also what keeps promoteNextQueuedToRunning / resolveQueuedUserBubble off
+     * them: those advance the SERVER queue, and a staged turn has no server
+     * request behind it yet.
+     *
+     * Returns the id to hand back as PinnedDispatchContext.stageId at dispatch.
+     */
+    stageOutgoingMessage(displayText: string): string;
+    private _stageIndex;
+    /**
+     * Where a staged turn belongs once it is finally sent: BELOW every indexing
+     * row, because that is the order it ran in and the order the server history
+     * will report on the next load (its request id is newer than every pass it
+     * waited for). While its files were uploading it sat above them — the rows
+     * are injected as each file's pass starts, after the bubble was staged.
+     *
+     * Returns the index to insert at, or -1 to leave the turn where it is. Never
+     * moves a turn UP: a bubble that already sits below the indexing rows (or a
+     * chat with no indexing at all) must not jump backwards over anything.
+     */
+    private _settledStagePosition;
+    /** The staged turn's files are up; it is now just waiting its place in the
+     *  queue. Drops the "(Uploading files...)" note back to "(In queue)". */
+    markStagedMessageQueued(stageId: string): void;
+    /**
+     * Resolves once this project's background-indexing queue has nothing left to
+     * run, so a chat enqueued right after it is genuinely last.
+     *
+     * Sending the chat as soon as the uploads finish is not enough, which is the
+     * whole reason this exists: indexing a file is a CHAIN, and each pass is only
+     * enqueued once the previous one lands (the client mints CONTINUE passes for
+     * text/grid files, the worker mints them for PDFs and windowed reads). Every
+     * one of those passes therefore queues up BEHIND a chat sent at upload time,
+     * and the model answers from a file it has only partly read.
+     *
+     * The queue is read from the server's status index rather than from
+     * bgTaskQueue: that mirror holds only what this client dispatched or adopted,
+     * and it stops being maintained once the view unmounts. An empty answer has to
+     * repeat before it is believed — see INDEXING_DRAIN_IDLE_LOOKS — and a look
+     * that fails counts as busy, so a dropped request delays the turn instead of
+     * releasing it early.
+     *
+     * Reads the identity PINNED at Send time, never a live one: the user may be in
+     * another project by now, and this must keep asking about the one they sent
+     * from.
+     */
+    awaitIndexingDrained(identity: ChatIdentity): Promise<'drained' | 'timedout' | 'skipped'>;
+    /**
+     * Abandon a staged turn — its uploads failed outright, so nothing will be
+     * dispatched. The bubble stays (the user's text is not silently thrown away)
+     * but settles into a plain, non-pending message; the caller reports the
+     * failure separately.
+     */
+    settleStagedMessage(stageId: string): void;
     dispatchComposedMessage(composed: string, useBgQueue?: boolean, composedForLlm?: string, extractContent?: any, fileUrls?: any, pinned?: PinnedDispatchContext): void;
     promoteNextBgQueuedToRunning(): void;
     promoteNextQueuedToRunning(): void;
@@ -1327,7 +1533,7 @@ declare class ChatSession {
         url: string;
         storagePath: string;
     }>>;
-    uploadPendingAttachments(): Promise<Array<{
+    uploadPendingAttachments(batchId?: string): Promise<Array<{
         name: string;
         url: string;
         storagePath?: string;
@@ -1336,4 +1542,4 @@ declare class ChatSession {
     bumpGate(): void;
 }
 
-export { type AiAgentPlatform, type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, type BgTaskEntry, type BoundedChatOptions, type BuildDisplayListOptions, type BuildIndexingUserMessageOptions, CLAUDE_INPUT_CAP_RATIO, CLAUDE_PER_REQUEST_INPUT_CAP, CONTEXT_WINDOW_BY_MODEL, CONTEXT_WINDOW_DEFAULT, type CallClaudeWithMcpParams, type ChatEngineConfig, type ChatHost, type ChatIdentity, type ChatMessage, ChatSession, type ChatState, type ChatSystemPromptParams, type ClaudeMcpServerRequest, type ClaudeMcpToolConfig, type ClaudeMessage, type ClaudeRole, type ComposedUserMessage, DEFAULT_CLAUDE_MODEL, DEFAULT_OPENAI_MODEL, type DisplayEntry, EXPIRED_ATTACHMENT_URL_HOST, EXPIRED_ATTACHMENT_URL_ORIGIN, EXPIRED_LINK_REFRESH_EXPIRES_SECONDS, type ExtractDirective, type FillHistoryViewportOptions, HISTORY_BUDGET_RATIO, HISTORY_FILL_SLACK_PX, HISTORY_TOKEN_BUDGET, type IndexingAttachmentInfo, type IndexingFileRef, type IndexingGroup, type IndexingGroupStatus, type IndexingRequestRef, type IndexingSystemPromptParams, type InlineLinkContext, type InlineLinkPart, LINK_LABEL_MAX_DISPLAY_CHARS, LINK_REFRESH_WINDOW_MS, MAX_HISTORY_FILL_PAGES, MAX_HISTORY_MESSAGES, MAX_PARSED_CONTENT_CHARS, MCP_NAME, MIN_INPUT_TOKEN_BUDGET, type MapHistoryOptions, OUTPUT_TOKEN_RESERVE, type OpenAIMessage, POLL_INTERVAL, type ParsedAiAgent, type PinnedDispatchContext, RENDER_FROM_TOKEN, TOOL_AND_RESPONSE_BUFFER, buildAiAgentValue, buildBoundedChatMessages, buildChatDisplayList, buildChatSystemPrompt, buildDisplayExpiredAttachmentHref, buildIndexingContinueMessage, buildIndexingRenderContinueTemplate, buildIndexingRenderMessage, buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingWindowMessage, callClaudeWithMcp, callClaudeWithPublicMcp, callOpenAIWithPublicMcp, chatEngineConfig, classifyInlineLink, clearAttachmentParsers, composeUserMessage, configureChatEngine, createHistoryFiller, createInlineLinkRegex, encodePathSegments, estimateMessageTokens, estimateTextTokens, extractClaudeText, extractLastUserTextFromRequest, extractOpenAIText, extractRemotePathFromAttachmentHref, fillHistoryViewport, filterListByClearHorizon, findAttachmentParser, formatChatTimestamp, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, getProjectContextWindow, groupAttachmentFailures, isAuthExpiredError, isBgIndexingQueue, isErrorResponseBody, isHttpUrlLike, isIndexingRequestText, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, makeExtractPlaceholder, mapHistoryListToMessages, normalizeAttachmentPathCandidate, normalizeTextContent, normalizeTrailingInlineToken, notifyAgentSaveAttachment, parseAiAgentValue, parseAttachmentContent, parseIndexingLabel, parseIndexingRequestText, readExpiredAttachmentHref, registerAttachmentParser, registerModelContextWindows, repairUrlEntities, repairUrlWhitespace, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, setProjectContextWindow, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay, wallClockNow };
+export { type AiAgentPlatform, type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, BOM, BOM_EXTS, type BgTaskEntry, type BoundedChatOptions, type BuildDisplayListOptions, type BuildIndexingUserMessageOptions, CLAUDE_INPUT_CAP_RATIO, CLAUDE_PER_REQUEST_INPUT_CAP, CONTEXT_WINDOW_BY_MODEL, CONTEXT_WINDOW_DEFAULT, type CallClaudeWithMcpParams, type ChatEngineConfig, type ChatHost, type ChatIdentity, type ChatMessage, ChatSession, type ChatState, type ChatSystemPromptParams, type ClaudeMcpServerRequest, type ClaudeMcpToolConfig, type ClaudeMessage, type ClaudeRole, type ComposedUserMessage, DEFAULT_CLAUDE_MODEL, DEFAULT_OPENAI_MODEL, type DisplayEntry, EXPIRED_ATTACHMENT_URL_HOST, EXPIRED_ATTACHMENT_URL_ORIGIN, EXPIRED_LINK_REFRESH_EXPIRES_SECONDS, EXT_CONTENT_TYPES, type EncodingClass, type ExtractDirective, type FillHistoryViewportOptions, HISTORY_BUDGET_RATIO, HISTORY_FILL_SLACK_PX, HISTORY_TOKEN_BUDGET, HTML_EXTS, HTML_HEAD_WINDOW, type IndexingAttachmentInfo, type IndexingFileRef, type IndexingGroup, type IndexingGroupStatus, type IndexingRequestRef, type IndexingSystemPromptParams, type InlineLinkContext, type InlineLinkPart, LINK_LABEL_MAX_DISPLAY_CHARS, LINK_REFRESH_WINDOW_MS, MAX_HISTORY_FILL_PAGES, MAX_HISTORY_MESSAGES, MAX_PARSED_CONTENT_CHARS, MCP_NAME, MIN_INPUT_TOKEN_BUDGET, type MapHistoryOptions, OUTPUT_TOKEN_RESERVE, type OpenAIMessage, POLL_INTERVAL, type ParsedAiAgent, type PinnedDispatchContext, RENDER_FROM_TOKEN, RTF_EXTS, TOOL_AND_RESPONSE_BUFFER, XML_EXTS, applyEncodingDeclaration, bgIndexingQueueName, buildAiAgentValue, buildBoundedChatMessages, buildChatDisplayList, buildChatSystemPrompt, buildDisplayExpiredAttachmentHref, buildIndexingContinueMessage, buildIndexingRenderContinueTemplate, buildIndexingRenderMessage, buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingWindowMessage, callClaudeWithMcp, callClaudeWithPublicMcp, callOpenAIWithPublicMcp, chatEngineConfig, classifyInlineLink, clearAttachmentParsers, composeUserMessage, configureChatEngine, contentTypeForExt, createHistoryFiller, createInlineLinkRegex, encodePathSegments, encodingClassForExt, ensureHtmlCharset, ensureXmlEncoding, escapeRtfNonAscii, estimateMessageTokens, estimateTextTokens, extOf, extractClaudeText, extractLastUserTextFromRequest, extractOpenAIText, extractRemotePathFromAttachmentHref, fillHistoryViewport, filterListByClearHorizon, findAttachmentParser, formatChatTimestamp, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, getProjectContextWindow, groupAttachmentFailures, hasBom, isAuthExpiredError, isBgIndexingQueue, isErrorResponseBody, isHttpUrlLike, isIndexingRequestText, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, looksLikeRtf, makeExtractPlaceholder, mapHistoryListToMessages, needsBomForExt, normalizeAttachmentPathCandidate, normalizeExt, normalizeTextContent, normalizeTrailingInlineToken, notifyAgentSaveAttachment, parseAiAgentValue, parseAttachmentContent, parseIndexingLabel, parseIndexingRequestText, prepareDownloadText, readExpiredAttachmentHref, registerAttachmentParser, registerModelContextWindows, repairUrlEntities, repairUrlWhitespace, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, setProjectContextWindow, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay, wallClockNow };