bunnyquery 1.6.0 → 1.7.0

package/dist/engine.d.mts

@@ -81,6 +81,20 @@ interface ChatEngineConfig {
      * `registerAttachmentParser()`. See attachment_parsers.ts.
      */
     attachmentParsers?: AttachmentParser[];
+    /**
+     * Opt in to SERVER-DRIVEN windowed indexing for text/grid files.
+     *
+     * Off by default, and deliberately so. When on, the client emits a
+     * `_skapi_window` directive and the WORKER reads the file one window at a time,
+     * continuing until the reader says it is exhausted. When off, the agent pages the
+     * file itself with readFileContent, exactly as before.
+     *
+     * The flag exists because the backend must ship FIRST: a client emitting the
+     * directive against a worker that does not strip it leaves an unknown field in the
+     * request body, and the provider rejects the whole call with no retry. Keep it off
+     * until the worker is deployed, then flip it per environment.
+     */
+    windowedIndexing?: boolean;
 }
 declare function configureChatEngine(config: ChatEngineConfig): void;
 declare function chatEngineConfig(): ChatEngineConfig;
@@ -241,18 +255,46 @@ type BuildIndexingUserMessageOptions = {
     pagedRead?: boolean;
 };
 declare function buildIndexingUserMessage(attachment: IndexingAttachmentInfo, options?: BuildIndexingUserMessageOptions): string;
+/**
+ * Token the WORKER substitutes with the 1-based first page of the window it is about to
+ * render, when it builds the next pass of a document from `RENDER_CONTINUE_TEMPLATE`.
+ * Must match the worker's RENDER_FROM_TOKEN.
+ */
+declare const RENDER_FROM_TOKEN = "{{RENDER_FROM}}";
 /**
  * User message for a VISION file (PDF): its pages are delivered as RENDERED PAGE IMAGES that
  * the proxy worker injects into THIS message at the `placeholder` token (tool-result images
  * render on neither provider, so the pages must be image blocks in the message itself). Each
- * pass shows one WINDOW of pages starting at `renderFrom` (0-based); the resume loop advances
- * the window a pass at a time until the injected note says the last window was reached.
+ * pass shows one WINDOW of pages starting at `renderFrom` (0-based).
+ *
+ * The WORKER advances the window: when its renderer reports pages remaining it enqueues the
+ * next pass itself, off the true page count, so a document indexes end-to-end with no browser
+ * involved. This message therefore only ever describes ONE window, and the model is never
+ * asked to decide whether the document is finished.
  *
  * renderFrom === 0 is the FIRST pass (leads with "A new file has just been uploaded." so the
- * client builds the "Indexing: <name>" bubble); renderFrom > 0 is a RESUME pass (leads with
- * "CONTINUE indexing" like the paged continue message, so it is not a duplicate primary bubble).
+ * client builds the "Indexing: <name>" bubble); a continue pass (built by the worker from
+ * buildIndexingRenderContinueTemplate) leads with "CONTINUE indexing" so it is not a duplicate
+ * primary bubble.
  */
 declare function buildIndexingRenderMessage(attachment: IndexingAttachmentInfo, placeholder: string, renderFrom: number): string;
+/**
+ * The CONTINUE pass, as a template the worker fills in. `pageLabel` defaults to the
+ * RENDER_FROM_TOKEN placeholder, which the worker replaces with the real 1-based start page
+ * of the window it is rendering; passing an explicit label produces a ready-to-send message.
+ */
+declare function buildIndexingRenderContinueTemplate(attachment: IndexingAttachmentInfo, placeholder: string, pageLabel?: string): string;
+/**
+ * User message for a WINDOWED file: the worker splices ONE window of the file's rows or
+ * text into this message at `placeholder`, then continues from the reader's own cursor
+ * until the file is exhausted.
+ *
+ * The agent is deliberately NOT asked to page the file itself, and is NOT asked to judge
+ * whether it is finished. Both used to be its job, and both failed the same way: the
+ * traversal lived inside a single turn's budget, so a large file simply stopped partway
+ * with a confident summary of the part it had seen.
+ */
+declare function buildIndexingWindowMessage(attachment: IndexingAttachmentInfo, placeholder: string, isContinuation: boolean, positionLabel?: string): string;
 /**
  * User message for a RESUME pass: a previous indexing pass could not finish this large
  * file, so continue it from where the already-saved records leave off (never restart).
@@ -314,6 +356,26 @@ declare function buildBoundedChatMessages(options: BoundedChatOptions): {
 declare var EXPIRED_ATTACHMENT_URL_HOST: string;
 declare var EXPIRED_ATTACHMENT_URL_ORIGIN: string;
 declare var LINK_LABEL_MAX_DISPLAY_CHARS: number;
+/**
+ * Lifetime of the url minted when a user clicks an expired attachment chip.
+ *
+ * Mint it as a PLAIN get-db presign, never with generate_temporary_cdn_url: the
+ * cdn branch ignores `expires` entirely and hands back a url good for the rest of
+ * the current UTC day plus the next one, so a "20 minute" link would in fact live
+ * 24 to 48 hours. The dashboard has always done this correctly and the widget did
+ * not, which is precisely the kind of divergence a shared constant exists to stop.
+ */
+declare var EXPIRED_LINK_REFRESH_EXPIRES_SECONDS: number;
+/**
+ * How long a client may keep serving an href it already minted before dropping
+ * back to the placeholder and re-minting.
+ *
+ * DERIVED from the TTL above, with five minutes of headroom, because the
+ * invariant "the cache must expire before the url does" used to be a comment
+ * next to two independent literals. If it is ever violated a client serves a
+ * dead url with no way to notice; deriving it makes that unrepresentable.
+ */
+declare var LINK_REFRESH_WINDOW_MS: number;
 declare function createInlineLinkRegex(): RegExp;
 declare function safeDecodeURIComponent(v: string): string;
 declare function encodePathSegments(path: string): string;
@@ -322,7 +384,86 @@ declare function extractRemotePathFromAttachmentHref(href: string, serviceId: st
 declare function getExpiredAttachmentVisiblePath(remotePath: string, fallback?: string): string;
 declare function buildDisplayExpiredAttachmentHref(remotePath: string, fallback?: string): string;
 declare function isServiceDbAttachmentHref(href: string, serviceId: string): boolean;
+/**
+ * Read the storage path back out of an `_expired_.url` placeholder.
+ *
+ * The placeholder is not a display detail: sanitizeAttachmentLinksForHistory
+ * writes it into PERSISTED history, and buildBoundedChatMessages replays it into
+ * the model's context. So it round-trips constantly and MUST be recognised on the
+ * way back in. Returns null for anything that is not the carrier.
+ */
+declare function readExpiredAttachmentHref(href: string): string | null;
 declare function sanitizeAttachmentLinksForHistory(content: string, serviceId: string, forAssistant?: boolean): string;
+/**
+ * Is this markdown link target a URL rather than a db storage path?
+ *
+ * The inline-link regex decides that by whether the target contains whitespace:
+ * its url branch forbids it, its bare-path branch allows it (a db path really can
+ * contain spaces). So a url that picked up a stray space anywhere in transit
+ * falls out of the url branch and is claimed by the path branch, and the view
+ * renders it as an `_expired_.url/https%3A/…` attachment chip that resolves to
+ * nothing. The view asks this FIRST, so what a link IS never depends on damage.
+ */
+declare function isHttpUrlLike(target: string): boolean;
+/**
+ * Repair whitespace inside a url. RFC 3986 has no legal whitespace anywhere in a
+ * URI, so a space in an href is always damage, never content.
+ *
+ * Two repairs, because the right one differs:
+ *   - Our own `/download/<id>` capability links (skapi-mcp file-download.js) are
+ *     base64url, optionally with a single `.` separating the payload and hmac of
+ *     the older self-describing token. That alphabet cannot contain whitespace,
+ *     so the spaces are purely damage and REMOVING them restores the exact link,
+ *     which is what makes an already-sent message clickable again. A model
+ *     reproducing one of these into its reply is exactly where the spaces come
+ *     from, which is also why the id is now short.
+ *   - Anything else keeps every character and only has the whitespace encoded,
+ *     the same thing a browser does with a space in an href. Stripping would be
+ *     wrong there: `…/exports/my report.csv` is a real file whose name has a
+ *     space in it, and deleting it points at a file that does not exist.
+ */
+declare function repairUrlWhitespace(href: string): string;
+/**
+ * Trim punctuation and unmatched wrappers that cling to a token in prose.
+ * `src::a/b.pdf).` -> `src::a/b.pdf`, while a balanced `file (v2).pdf` is kept.
+ */
+declare function normalizeTrailingInlineToken(value: string): string;
+/** A link the view renders. `expired` means the href is the `_expired_.url`
+ *  placeholder and a click must mint a fresh one from `remotePath`. */
+interface InlineLinkPart {
+    type: 'link';
+    label: string;
+    fullLabel: string;
+    href: string;
+    expired: boolean;
+    expiredHref?: string;
+    remotePath?: string;
+}
+interface InlineLinkContext {
+    /** Current project id: the leading segment to strip off a db url. */
+    serviceId: string;
+    /** `https://db.<hostDomain>` for this deployment. */
+    dbHostPrefix: string;
+    /** A fresh url already minted for this placeholder, if the view cached one. */
+    resolveFreshHref?: (expiredHref: string) => string | undefined;
+}
+/**
+ * Decide what ONE inline-link regex match actually is, and how to render it.
+ *
+ * This is the single place that answers "is this an external url, this project's
+ * db file, or a bare storage path", for every consumer. It used to live twice,
+ * once in agent.vue and once in the widget, and both copies had to be found and
+ * corrected for each of the link bugs this file's history records. A view now
+ * supplies its own context (project id, db host, cached-href lookup) and does
+ * nothing but turn the returned part into markup.
+ *
+ * `groups` is [g1..g6] from createInlineLinkRegex, in that order:
+ *   g1 src::<token>   g2/g3 [label](url)   g4/g5 [label](path)   g6 bare url
+ */
+declare function classifyInlineLink(full: string, groups: Array<string | undefined>, ctx: InlineLinkContext): {
+    part: InlineLinkPart;
+    tail?: string;
+} | null;
 declare function truncateLabelForDisplay(label: string): string;
 
 declare function filterListByClearHorizon(list: any[], clearedAt: number): any[];
@@ -332,16 +473,107 @@ type MapHistoryOptions = {
     clearedAt: number;
     serviceId: string;
     /** View-side display formatter for "Indexing:/Reindexing: …" bubbles. */
-    formatIndexingLabel: (name: string, mime?: string, size?: number | null, storagePath?: string) => string;
+    formatIndexingLabel: (name: string, mime?: string, size?: number | null, storagePath?: string, reindex?: boolean, continued?: boolean) => string;
 };
 declare function mapHistoryListToMessages(list: any[], platform: 'claude' | 'openai', opts: MapHistoryOptions): {
     messages: any[];
     runningItemIds: string[];
 };
 
+/**
+ * Keep older history REACHABLE by paging until the message box actually gains
+ * something to scroll to.
+ *
+ * Older history is paged in by one trigger only: the user scrolling to the top
+ * of the message box. That trigger has two ways to die, and collapsed indexing
+ * rows cause both:
+ *
+ *   1. The box never scrolls. A file's every indexing pass (the first plus every
+ *      CONTINUE pass, request AND response bubble each) folds into ONE row, so a
+ *      full history page — twenty-plus messages — can render as a single line.
+ *      Content shorter than the viewport fires no scroll event, so page 2 is
+ *      never requested and any conversation the user had before that upload is
+ *      permanently out of reach.
+ *   2. The fetched page adds no height. A page that is entirely the same file's
+ *      earlier passes joins the collapsed row already on screen and renders
+ *      nothing new. The user, sitting at scrollTop 0, scrolls up again — and
+ *      because the position never changed, no further scroll event fires.
+ *
+ * Both are the same shape: fetch, re-measure, and keep going until the user
+ * genuinely gained reachable content, history ran out, or the pager stopped
+ * advancing. `isSatisfied` is what differs between the two (can the box scroll
+ * at all / did it grow), so the loop below takes it as a predicate.
+ *
+ * DOM-free like the rest of the engine — the caller supplies the measurement and
+ * awaits its own render before measuring, so agent.vue and the widget run the
+ * identical loop over their own pagers.
+ */
+/** Overflow (px) that counts as "the user can scroll here". Comfortably more
+ *  than the 60px top threshold that triggers the next page, so a filled box has
+ *  real room to scroll rather than sitting one pixel from the trigger. */
+declare const HISTORY_FILL_SLACK_PX = 64;
+/** Pages one fill pass will request before giving up. Reached only by a chat
+ *  whose history really is dozens of pages of one file's indexing passes; the
+ *  cap exists so a pager that stops advancing can never spin forever. */
+declare const MAX_HISTORY_FILL_PAGES = 24;
+type FillHistoryViewportOptions = {
+    /** The user has reachable content and paging can stop. Called AFTER the
+     *  caller's own render has settled (nextTick / rAF), since only the caller
+     *  knows when its view has painted — hence the allowance for a promise. */
+    isSatisfied: () => boolean | Promise<boolean>;
+    /** All history is loaded — nothing left to page in. */
+    isEndOfList: () => boolean;
+    /** A history request is already in flight. Waited out, not treated as a stop
+     *  condition: a background first-page refresh (the queue-detect tick fires one
+     *  every couple of seconds while a file is indexing) would otherwise swallow
+     *  the user's scroll-up entirely, and scrolling up again from scrollTop 0
+     *  produces no second event to retry with. */
+    isLoading: () => boolean;
+    /** Messages currently loaded. Used to detect a page that added nothing, which
+     *  means the pager is not advancing and looping would never terminate. */
+    messageCount: () => number;
+    /** Fetch ONE older page (the caller's own fetchMore path, scroll-restore and
+     *  all). Return `false` when the request was NOT issued (the caller's own
+     *  single-flight guard swallowed it) so the loop retries instead of reading
+     *  the unchanged message count as an exhausted pager. Anything else, including
+     *  undefined, means it was attempted. */
+    fetchOlder: () => Promise<boolean | void | any>;
+    /** The chat this fill was started for is gone (project switched, view
+     *  unmounted, gate token bumped). Checked between pages so a stale fill can
+     *  never keep paging another chat's history. */
+    isStale?: () => boolean;
+    maxPages?: number;
+};
+/**
+ * Page older history until `isSatisfied`, until history runs out, or until the
+ * pager stops advancing. Never throws: a failed page ends the fill, and the
+ * user's own scrolling remains the fallback trigger.
+ */
+declare function fillHistoryViewport(opts: FillHistoryViewportOptions): Promise<void>;
+/**
+ * One fill loop per view, with predicates COMBINED rather than dropped.
+ *
+ * Fills come from several places at once — a first page finishing, a window
+ * resize, a row being collapsed, and the user's own scroll to the top — and a
+ * plain "one at a time, drop the rest" guard picks the wrong winner: a resize
+ * fill (satisfied the moment the box can scroll at all) would swallow the user's
+ * scroll-up (which needs content specifically ABOVE them), and the scroll-up
+ * cannot be retried, because a reader parked at scrollTop 0 produces no further
+ * scroll event. Dropping the guard entirely is no better: every frame of a
+ * window drag would start its own 24-page loop.
+ *
+ * So a request that arrives mid-loop ANDs its predicate into the running one:
+ * the loop then keeps paging until EVERY caller is satisfied. Predicates that
+ * come true are dropped as it goes, so the cost stays flat.
+ */
+declare function createHistoryFiller(base: Omit<FillHistoryViewportOptions, 'isSatisfied'>): {
+    fill: (isSatisfied: () => boolean | Promise<boolean>) => Promise<void>;
+    isRunning: () => boolean;
+};
+
 declare const MCP_NAME = "BunnyQuery";
 declare const DEFAULT_CLAUDE_MODEL = "claude-sonnet-4-6";
-declare const DEFAULT_OPENAI_MODEL = "gpt-5.4";
+declare const DEFAULT_OPENAI_MODEL = "gpt-5.6-luna";
 type ClaudeRole = 'user' | 'assistant';
 type ClaudeMessage = {
     role: ClaudeRole;
@@ -423,6 +655,16 @@ 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";
+/**
+ * True when a request belongs to the background-indexing queue.
+ *
+ * Accepts BOTH shapes this value arrives in: the bare queue name the client sends
+ * ("<userId>-bg"), and the server qid that comes back on history/poll responses
+ * ("<service>:<queue>|<seq>"). Testing the tail of the raw value only works for the
+ * first: a qid ends in "|<seq>", so `endsWith('-bg')` is always false for it — which
+ * silently meant history items were NEVER recognised as background tasks.
+ */
+declare function isBgIndexingQueue(queueName?: string): boolean;
 type BgTaskEntry = {
     serviceId: string;
     platform: 'claude' | 'openai';
@@ -464,6 +706,35 @@ interface ChatIdentity {
     serviceName?: string;
     serviceDescription?: string;
 }
+/**
+ * Project context captured at the moment the user hit Send, so a turn whose
+ * dispatch is delayed (attachment uploads are awaited first) still reaches the
+ * project the question was asked of rather than whichever project the user has
+ * navigated to by then. Both fields are identity-derived and must be snapshotted
+ * together — the system prompt embeds the service name/description/id.
+ */
+interface PinnedDispatchContext {
+    identity: ChatIdentity;
+    systemPrompt: string;
+}
+/**
+ * The file a background-indexing bubble belongs to. Stamped on the REQUEST
+ * bubble (both the live one and the one rebuilt from history) so the display
+ * layer can group a file's many passes without reverse-parsing the view's
+ * formatted label. See indexing_groups.buildChatDisplayList.
+ */
+interface IndexingFileRef {
+    name: string;
+    /** Storage path, when known. Preferred group identity: a file can be
+     *  re-uploaded under a name that already exists elsewhere. */
+    path?: string;
+    mime?: string;
+    size?: number;
+    isReindex?: boolean;
+    /** A CONTINUE pass. Its absence across every loaded pass is what tells the
+     *  display layer that earlier passes are still unpaged. */
+    continued?: boolean;
+}
 interface ChatMessage {
     role: 'user' | 'assistant';
     content: string;
@@ -475,11 +746,14 @@ interface ChatMessage {
     isCancelled?: boolean;
     isError?: boolean;
     isBackgroundTask?: boolean;
+    /** Set on background-indexing REQUEST bubbles only (see IndexingFileRef). */
+    _indexFile?: IndexingFileRef;
     _useBgQueue?: boolean;
     _serverItemId?: string;
     _localId?: string;
     _cancelling?: boolean;
     _cancelError?: string;
+    _ownerKey?: string;
 }
 interface ChatState {
     messages: ChatMessage[];
@@ -509,6 +783,12 @@ interface ChatHost {
     scrollToBottom(smooth?: boolean): Promise<void> | void;
     /** Scroll only if the user is pinned to the bottom (does not force-pin). */
     scrollToBottomIfSticky(smooth?: boolean): Promise<void> | void;
+    /** A history page finished loading and rendering. OPTIONAL. The view uses it
+     *  to page further when the message box came out too short to scroll — the
+     *  only trigger for loading older history is a scroll to the top, so a box
+     *  that cannot scroll has no way to reach page 2 (see viewport_fill). Only
+     *  the view can measure that, which is why the engine merely announces it. */
+    onHistoryLoaded?(fetchMore: boolean, token: number): void;
     cancelRequest(opts: {
         url: string;
         method: string;
@@ -522,7 +802,7 @@ interface ChatHost {
     } | any>;
     refreshSession(): Promise<boolean>;
     /** Build the "Indexing:/Reindexing: …" label (view-side display formatting). */
-    formatIndexingLabel(name: string, mime?: string, size?: number | null, storagePath?: string, reindex?: boolean): string;
+    formatIndexingLabel(name: string, mime?: string, size?: number | null, storagePath?: string, reindex?: boolean, continued?: boolean): string;
     /** drainBgTaskQueue is a no-op until the chat view is mounted. */
     isViewMounted(): boolean;
     /** Clear-horizon timestamp (localStorage, per service#platform) — view-owned. */
@@ -556,6 +836,105 @@ interface ChatHost {
     updateComposerControls(): void;
 }
 
+/**
+ * Background file-indexing turns, collapsed into ONE row per file.
+ *
+ * A single upload can produce many chat turns: the first "Indexing: <file>" pass
+ * plus up to MAX_INDEXING_RESUME_PASSES CONTINUE passes, each with its own
+ * request AND response bubble. Rendered flat, that reads as the same task
+ * repeating forever, and any real question the user asks in between gets buried.
+ *
+ * buildChatDisplayList turns the flat message array into a DISPLAY list in which
+ * every message belonging to one file (however far apart they sit, and whatever
+ * else is interleaved between them) is represented by a single group entry,
+ * rendered at the position of that file's NEWEST turn. Newest, not oldest, so:
+ *   - a running index sits at the bottom, where the activity is, and
+ *   - paging older history in never moves a row that is already on screen
+ *     (older passes simply join the group they already belong to).
+ *
+ * The group deliberately reports no authoritative pass TOTAL. History is paged
+ * newest-first, so any total computed from loaded messages is a lower bound that
+ * a later scroll-up would contradict. It reports STATE (indexing / indexed /
+ * failed), how many passes are currently loaded, and `mayHaveOlder` when the
+ * file's first pass is not among them.
+ *
+ * Pure and view-agnostic: agent.vue and the BunnyQuery widget both render from
+ * this, so the two stay identical.
+ */
+
+type IndexingGroupStatus = 'active' | 'done' | 'error' | 'cancelled';
+type IndexingGroup = {
+    /** The FILE this row is about: storage path when known (a file can be
+     *  re-uploaded under a name that already exists elsewhere), else name. Shared
+     *  by every run of that file, and what ChatSession.cancelIndexingGroup and
+     *  _indexKeyOf match on — never use it as a render key. */
+    key: string;
+    /** Identity of this ROW: one indexing RUN of that file. A file indexed on
+     *  Monday and re-indexed on Wednesday is two runs, and collapsing them into
+     *  one row erased Monday's from Monday's place in the conversation, claimed
+     *  its passes for Wednesday, and let Monday's failure be overwritten by
+     *  Wednesday's success. Numbered from the NEWEST run backwards (`#0` is the
+     *  newest) so paging in older history never renames a row already on screen.
+     *  This is the render key and the expansion key. */
+    runKey: string;
+    name: string;
+    path?: string;
+    mime?: string;
+    size?: number;
+    /** True when any loaded pass was a re-index of an already-stored file. */
+    isReindex: boolean;
+    /** Every message of this file, in chat order, with its index in the source
+     *  array (so cancel/typewriter paths keep addressing the real message). */
+    members: {
+        msg: ChatMessage;
+        index: number;
+    }[];
+    /** Indexing passes LOADED (request bubbles), never a server-side total. */
+    passCount: number;
+    status: IndexingGroupStatus;
+    /** Server item ids of the passes that are still queued/running, so the row can
+     *  offer a stop button (ChatSession.cancelIndexingGroup cancels each). Empty
+     *  when nothing is cancellable — a finished file, or a live pass whose server
+     *  id has not come back yet. */
+    cancellableIds: string[];
+    /** A cancel request is in flight for one of the passes. */
+    cancelling: boolean;
+    /** Why the last cancel attempt failed (e.g. the pass had already finished). */
+    cancelError?: string;
+    /** The file's first pass is not among the loaded messages, so earlier passes
+     *  exist in history that has not been paged in yet. */
+    mayHaveOlder: boolean;
+    /** Position in the source array this collapsed row renders at. */
+    anchorIndex: number;
+};
+type DisplayEntry = {
+    kind: 'message';
+    msg: ChatMessage;
+    index: number;
+} | {
+    kind: 'indexing';
+    group: IndexingGroup;
+    index: number;
+};
+type BuildDisplayListOptions = {
+    /** True while older history remains unpaged, which is what makes a group
+     *  with no first pass genuinely incomplete rather than merely odd. */
+    hasMoreHistory?: boolean;
+};
+declare function parseIndexingLabel(content: string): {
+    name: string;
+    path?: string;
+    continued: boolean;
+    isReindex: boolean;
+} | null;
+/**
+ * Collapse background-indexing turns into per-file groups.
+ *
+ * Messages that are not background-indexing pass through untouched, at their
+ * original positions and with their original indices.
+ */
+declare function buildChatDisplayList(messages: ChatMessage[], opts?: BuildDisplayListOptions): DisplayEntry[];
+
 /**
  * ChatSession — framework-agnostic stateful chat orchestration.
  *
@@ -576,33 +955,126 @@ interface ChatHost {
  * session via the public methods and re-renders in host.notify().
  */
 
+/** A live poll registered in ChatSession.historyItemPolls. */
+type PollHandle = {
+    /** 'bg' = background indexing, pausable. 'fg' = a reply the user is waiting on. */
+    kind: 'fg' | 'bg';
+    /** Absent on an older skapi-js that cannot stop an attached poll. */
+    stop?: () => void;
+};
 declare class ChatSession {
     host: ChatHost;
     state: ChatState;
     bgTaskQueue: BgTaskEntry[];
     cancelledServerIds: Set<string>;
+    /** Files whose indexing the user stopped, keyed exactly as buildChatDisplayList
+     *  keys a group (storage path, else filename). Cancelling one pass is not
+     *  enough on its own: the client dispatches CONTINUE passes for paged files, so
+     *  without this the next pass is enqueued the moment the cancelled one settles.
+     *  Cleared when a FIRST pass for the same file is queued again (a re-upload or a
+     *  Reindex from the file manager), so stopping a file never poisons it. */
+    cancelledIndexKeys: Set<string>;
     pendingAgentRequests: Record<string, Promise<any>>;
     aiChatHistoryCache: Record<string, {
         messages: ChatMessage[];
         endOfList: boolean;
         startKeyHistory: string[];
     }>;
-    historyItemPolls: Map<string, boolean>;
+    historyItemPolls: Map<string, PollHandle>;
+    /** Non-empty while polling is paused; keyed by reason so overlapping causes
+     * (view detached AND tab hidden) do not resume each other prematurely. */
+    private _pauseReasons;
+    private _resuming;
     private _lidSeq;
     constructor(host: ChatHost);
+    /**
+     * 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.
+     *
+     * `stop` comes from the SDK and may be absent on an older skapi-js, in which case the
+     * poll simply cannot be stopped and is left running — see pausePolling.
+     */
+    private _trackPoll;
+    /**
+     * Stop and forget one item's poll. Used after a cancel: the row is either gone
+     * (cancelled while queued) or flagged cancelled (cancelled while running), so
+     * asking about it again only burns requests. Safe when no poll is attached, and
+     * safe on an older skapi-js with no stop handle (the entry is then LEFT in the
+     * map so a later drain cannot stack a second, unstoppable poll on the id).
+     */
+    private _stopPoll;
+    /** True while any pause reason is active. */
+    isPollingPaused(): boolean;
+    /**
+     * Stop BACKGROUND polling until resumePolling. Foreground polls (a reply the user is
+     * waiting on) keep running deliberately: their results must still land in the history
+     * cache so resumePendingRequest can render them on return, otherwise a user who sends
+     * a message then navigates away comes back to a permanently stuck "Thinking...".
+     *
+     * Server-side work is untouched; this only stops asking about it. That is safe for
+     * document indexing because the worker drives that loop itself.
+     */
+    pausePolling(reason: string): void;
+    /**
+     * Lift a pause reason WITHOUT running the reconcile. For a caller that is about to
+     * reload history anyway (a view remounting), letting resumePolling also reconcile
+     * would race that load and can double-attach.
+     */
+    clearPauseReason(reason: string): void;
+    /**
+     * Clear a pause reason and, once none remain, re-attach polling and reconcile.
+     * Deliberately does NOT touch gateRefreshToken: bumping it would silently discard
+     * the results of anything still in flight across the pause.
+     */
+    resumePolling(reason: string): Promise<void>;
     private _newLocalId;
     getHistoryCacheKey(): string;
     updateHistoryCache(): void;
+    /**
+     * Land a resolved reply in the history cache of a chat that is NOT currently
+     * visible, without touching state.messages. Mirrors the cache-only path in
+     * dispatchAgentRequest: REPLACE the trailing pending "Thinking..." bubble
+     * (append only when there is none), and settle the matching pending user
+     * bubble, so the cached copy never keeps a stuck "Thinking..." that a later
+     * cache-first load would re-render forever.
+     */
+    private _applyReplyToCache;
+    /**
+     * serviceId/owner are passed explicitly by every caller: a request can be
+     * dispatched after the user moved to another project, and re-reading the live
+     * identity here would silently send the turn to THAT project instead of the
+     * one it was composed for. Falls back to the live read only when a caller
+     * omits them.
+     */
     private _callProviderFor;
     dispatchAgentRequest(params: any): Promise<any>;
-    dispatchComposedMessage(composed: string, useBgQueue?: boolean, composedForLlm?: string, extractContent?: any, fileUrls?: any): void;
+    dispatchComposedMessage(composed: string, useBgQueue?: boolean, composedForLlm?: string, extractContent?: any, fileUrls?: any, pinned?: PinnedDispatchContext): void;
     promoteNextBgQueuedToRunning(): void;
     promoteNextQueuedToRunning(): void;
     resolveQueuedUserBubble(serverId?: string): number | undefined;
     insertAtTarget(msg: ChatMessage, targetIdx: number): void;
-    onQueuedSendResponse(_composed: string, response: any, platform: string, serverId?: string): void;
-    onQueuedSendError(_composed: string, err: any, serverId?: string): void;
+    onQueuedSendResponse(_composed: string, response: any, platform: string, serverId?: string, ownerKey?: string): void;
+    onQueuedSendError(_composed: string, err: any, serverId?: string, ownerKey?: string): void;
     cancelQueuedMessage(msg: ChatMessage, idx: number): void;
+    /**
+     * Stop indexing a file, from its collapsed row — every pass at once, not just
+     * the bubble the user happens to see.
+     *
+     * A big file is indexed as a CHAIN of passes, so cancelling only the live one
+     * accomplishes nothing: the next pass is dispatched as soon as it settles.
+     * Three things end the chain:
+     *   1. every queued/running pass of this file is cancelled server-side
+     *      (csr-cancel deletes a queued row and flags a running one "cancelled",
+     *      which is also the worker's gate for NOT enqueueing the next window);
+     *   2. the file is remembered in cancelledIndexKeys, so the client-driven
+     *      resume (maybeResumeIndexing) stops dispatching CONTINUE passes; and
+     *   3. any of its passes still sitting in bgTaskQueue is dropped by the next
+     *      drain rather than surfacing a fresh "Indexing…" bubble.
+     *
+     * Records already written by the passes that DID run are kept — this stops the
+     * work, it does not undo it.
+     */
+    cancelIndexingGroup(group: IndexingGroup): void;
     typewriteIntoIndex(idx: number, fullText: string, localId?: string): Promise<void>;
     private typewriterQueue;
     enqueueTypewrite(idx: number, fullText: string, localId?: string): Promise<any>;
@@ -612,6 +1084,39 @@ declare class ChatSession {
     resumePendingRequest(token: number): Promise<void>;
     handleHistoryItemResolution(itemId: string, response: any, platform: string): void;
     applyHistoryItemResolution(itemId: string, response: any, platform: string): void;
+    /** How a bg task maps onto a collapsed row: the row's own key (storage path
+     *  when known, else the filename), scoped to the chat it belongs to. A storage
+     *  path is project-relative ("report.xlsx"), and ONE ChatSession serves every
+     *  project — unscoped, stopping a file in one project would silently suppress
+     *  the same filename's continuations in another. */
+    private _indexKeyOf;
+    /**
+     * Reconcile the bg queue with the files the user has stopped.
+     *
+     * A FIRST pass (no resumePass) is a fresh indexing request — a re-upload, or a
+     * Reindex from the file manager — so it LIFTS the stop: the key is a storage
+     * path, and without this an earlier cancel would silently kill every future
+     * index of the same path. A continuation of a stopped file is dropped instead,
+     * covering the pass that was dispatched in the moment before the cancel landed.
+     */
+    private _applyIndexCancellations;
+    /**
+     * Cancel any live pass of a stopped file that turned up on its own.
+     *
+     * The client is not the only thing that continues a file: for PDFs and (when
+     * windowed indexing is on) text/grid files the WORKER enqueues the next window
+     * itself, and that pass reaches the chat through the history poll, never
+     * through bgTaskQueue. The worker's own gate stops the chain when the running
+     * row is cancelled — but if the row had already finished when the user hit
+     * stop, the next window was queued a moment earlier and still arrives. Stop it
+     * here rather than making the user hit stop again.
+     *
+     * Runs from drainBgTaskQueue, which both clients call after a history load.
+     */
+    private _sweepCancelledIndexing;
+    /** Best-effort server-side cancel of a bg-queue item that has no bubble (so
+     *  cancelQueuedMessage, which drives one, has nothing to act on). */
+    private _cancelServerItem;
     drainBgTaskQueue(): void;
     maybeResumeIndexing(entry: BgTaskEntry, response: any, platform: string): void;
     loadHistory(fetchMore?: boolean, token?: number): Promise<void>;
@@ -629,4 +1134,4 @@ declare class ChatSession {
     bumpGate(): void;
 }
 
-export { type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, type BgTaskEntry, type BoundedChatOptions, type BuildIndexingUserMessageOptions, 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, EXPIRED_ATTACHMENT_URL_HOST, EXPIRED_ATTACHMENT_URL_ORIGIN, type ExtractDirective, HISTORY_TOKEN_BUDGET, type IndexingAttachmentInfo, type IndexingSystemPromptParams, LINK_LABEL_MAX_DISPLAY_CHARS, MAX_HISTORY_MESSAGES, MAX_PARSED_CONTENT_CHARS, MCP_NAME, MIN_INPUT_TOKEN_BUDGET, type MapHistoryOptions, OUTPUT_TOKEN_RESERVE, type OpenAIMessage, POLL_INTERVAL, TOOL_AND_RESPONSE_BUFFER, buildBoundedChatMessages, buildChatSystemPrompt, buildDisplayExpiredAttachmentHref, buildIndexingContinueMessage, buildIndexingRenderMessage, buildIndexingSystemPrompt, buildIndexingUserMessage, callClaudeWithMcp, callClaudeWithPublicMcp, callOpenAIWithPublicMcp, chatEngineConfig, clearAttachmentParsers, composeUserMessage, configureChatEngine, createInlineLinkRegex, encodePathSegments, estimateMessageTokens, estimateTextTokens, extractClaudeText, extractLastUserTextFromRequest, extractOpenAIText, extractRemotePathFromAttachmentHref, filterListByClearHorizon, findAttachmentParser, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, groupAttachmentFailures, isAuthExpiredError, isErrorResponseBody, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, makeExtractPlaceholder, mapHistoryListToMessages, normalizeAttachmentPathCandidate, normalizeTextContent, notifyAgentSaveAttachment, parseAttachmentContent, registerAttachmentParser, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay };
+export { type AttachmentFailureGroup, type AttachmentParser, type AttachmentSaveInfo, BG_INDEXING_QUEUE_SUFFIX, type BgTaskEntry, type BoundedChatOptions, type BuildDisplayListOptions, type BuildIndexingUserMessageOptions, 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_FILL_SLACK_PX, HISTORY_TOKEN_BUDGET, type IndexingAttachmentInfo, type IndexingFileRef, type IndexingGroup, type IndexingGroupStatus, 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 PinnedDispatchContext, RENDER_FROM_TOKEN, TOOL_AND_RESPONSE_BUFFER, 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, getAttachmentParsers, getChatHistory, getContextWindow, getErrorMessage, getExpiredAttachmentVisiblePath, groupAttachmentFailures, isAuthExpiredError, isBgIndexingQueue, isErrorResponseBody, isHttpUrlLike, isNonRetryableRequestError, isOfficeFile, isServerExtractable, isServiceDbAttachmentHref, listClaudeModels, listOpenAIModels, makeExtractPlaceholder, mapHistoryListToMessages, normalizeAttachmentPathCandidate, normalizeTextContent, normalizeTrailingInlineToken, notifyAgentSaveAttachment, parseAttachmentContent, parseIndexingLabel, readExpiredAttachmentHref, registerAttachmentParser, repairUrlWhitespace, safeDecodeURIComponent, sanitizeAttachmentLinksForHistory, stripFileBlocksFromHistory, transformContentWithImages, transformContentWithOpenAIImages, truncateLabelForDisplay };