bunnyquery 1.5.6 → 1.6.0

package/package.json

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

package/src/engine/office.ts

@@ -101,6 +101,42 @@ export function isServerExtractable(name?: string, mime?: string): boolean {
 /** @deprecated renamed to {@link isServerExtractable} (now also covers text files). */
 export const isOfficeFile = isServerExtractable;
 
+// Extensions that are best read WINDOW-BY-WINDOW via the readFileContent tool instead of
+// inlined once: spreadsheets (grid rows + embedded photos, and can be huge) and PDFs
+// (scanned page images). For these the indexing agent is told to page through the whole
+// file with readFileContent rather than reading a capped inline dump or web_fetching a URL.
+const PAGED_READ_EXTENSIONS = new Set(['xls', 'xlsx', 'xlsm', 'ods', 'pdf']);
+
+/**
+ * True when a file should be indexed by PAGING through readFileContent (spreadsheets and
+ * PDFs), rather than inline extraction or a web_fetch URL. This is what lets a huge sheet
+ * be read row-window by row-window and a scanned PDF be read page-image by page-image,
+ * with embedded photos delivered to the vision model.
+ */
+export function isPagedReadFile(name?: string, mime?: string): boolean {
+	const ext = (name || '').split('.').pop()?.toLowerCase() || '';
+	if (PAGED_READ_EXTENSIONS.has(ext)) return true;
+	const m = (mime || '').toLowerCase();
+	return (
+		m === 'application/pdf' ||
+		m === 'application/vnd.ms-excel' ||
+		m.includes('spreadsheetml') ||
+		m.includes('opendocument.spreadsheet')
+	);
+}
+
+/**
+ * True for files whose content is VISUAL and must be delivered to the model as IMAGE
+ * BLOCKS in the message (rendered pages), because tool-result images render on neither
+ * provider. The worker renders a page window to image URLs and injects them (`_skapi_render`
+ * directive). Currently PDFs (scanned or not); indexed page-window by page-window with
+ * resume advancing the window.
+ */
+export function isImageVisionFile(name?: string, mime?: string): boolean {
+	const ext = (name || '').split('.').pop()?.toLowerCase() || '';
+	return ext === 'pdf' || (mime || '').toLowerCase() === 'application/pdf';
+}
+
 // Monotonic counter so placeholders are unique even for same-named files in one
 // request. Token shape must match the worker's _EXTRACT_PLACEHOLDER_RE:
 // {{SKAPI_FILE_CONTENT::<id>}}.
@@ -111,6 +147,19 @@ export function makeExtractPlaceholder(seed: string): string {
 	return `{{SKAPI_FILE_CONTENT::${slug}-${_extractPlaceholderSeq}}}`;
 }
 
+// Placeholder marking WHERE the worker injects a window of rendered page/photo IMAGE blocks
+// (the `_skapi_render` directive). Distinct token from the text-extraction placeholder.
+let _renderPlaceholderSeq = 0;
+export function makeRenderPlaceholder(seed: string): string {
+	_renderPlaceholderSeq += 1;
+	const slug = (seed || 'file').replace(/[^a-zA-Z0-9]+/g, '_').slice(-48);
+	return `{{SKAPI_RENDER::${slug}-${_renderPlaceholderSeq}}}`;
+}
+
+// Page/photo images per render window. Must match the server default so the client's
+// resume window (from = pass * PAGES) lines up with what the worker renders.
+export const RENDER_PAGES_PER_WINDOW = 5;
+
 export interface ComposedUserMessage {
 	/** Clean display/history copy (attachment links, NO extraction placeholders). */
 	composed: string;

package/src/engine/prompts/index.ts

@@ -9,6 +9,8 @@ export { buildChatSystemPrompt, type ChatSystemPromptParams } from './chat_syste
 export { buildIndexingSystemPrompt, type IndexingSystemPromptParams } from './indexing_system_prompt';
 export {
 	buildIndexingUserMessage,
+	buildIndexingContinueMessage,
+	buildIndexingRenderMessage,
 	type IndexingAttachmentInfo,
 	type BuildIndexingUserMessageOptions,
 } from './indexing_user_message';

package/src/engine/prompts/indexing_system_prompt.ts

@@ -23,12 +23,14 @@ export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): s
 `You are a background indexing agent for project ${service}.
 - Image files (.jpg, .jpeg, .png, .gif, .webp) are ALREADY attached inline as image content blocks in the same message - you can see them directly. Do NOT call web_fetch on image URLs; that will fail or return garbage. Just look at the image block and answer.
 - Most files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) have ALREADY been extracted on the server and included inline in the user message between the "BEGIN FILE CONTENT" / "END FILE CONTENT" markers - read that directly. If the inline content is a "[skapi: ...]" note, the file could not be extracted - index it from its metadata only.
-- BIG or SCANNED files: the inline content may be only the FIRST part of a large file (it can end with a truncation or "more remains" note), and scanned PDFs / files with embedded photos are not fully captured inline. In those cases READ THE FILE WITH THE readFileContent TOOL: it returns the file ONE WINDOW at a time (spreadsheets as coordinate-tagged grid rows, scanned/large PDFs as rendered PAGE IMAGES, text as a range of characters). Pass the file's storage path. After each window: datafy it into records and SAVE them, THEN if the window says MORE REMAINS call readFileContent again with the cursor it gives you. Repeat until it says END OF FILE, so the WHOLE file is indexed - never stop after the first window.
-- VISION: when a readFileContent window (or an inline attachment) includes IMAGES - scanned PDF pages, or photos embedded in a spreadsheet next to a row/block - LOOK at them and capture what they show as record data (the reading/values in a scanned table, the part/defect/condition visible in a photo). The image IS part of the data; correlate each photo with its labelled block ("PHOTO A3" markers tie a photo to that grid row).
+- BIG SPREADSHEETS / TEXT: the inline content may be only the FIRST part of a large file (it can end with a truncation or "more remains" note). For big spreadsheets and big text/data files READ THE FILE WITH THE readFileContent TOOL: it returns the file ONE WINDOW at a time (spreadsheets as coordinate-tagged grid rows, text as a range of characters). Pass the file's storage path. After each window: datafy it into records and SAVE them, THEN if the window says MORE REMAINS call readFileContent again with the cursor it gives you. Repeat until it says END OF FILE, so the WHOLE file is indexed - never stop after the first window. (Do NOT call readFileContent on a PDF - see the next line.)
+- PDFs (scanned or not): you do NOT read a PDF with a tool or a URL. Its pages are RENDERED and embedded directly in the user message as IMAGE blocks, a WINDOW of pages at a time. LOOK at the embedded page images and datafy every one. The note beside them tells you whether MORE pages remain: if so, save this window's records and stop (a follow-up pass shows the next window automatically); only when the note says it was the LAST window is the PDF fully seen. Do NOT call readFileContent or web_fetch for a PDF.
+- VISION: when the message (a readFileContent window, an embedded PDF page, or an inline attachment) includes IMAGES - scanned/rendered PDF pages, or photos embedded in a spreadsheet next to a row/block - LOOK at them and capture what they show as record data (the reading/values in a scanned table, the part/defect/condition visible in a photo). The image IS part of the data; correlate each photo with its labelled block ("PHOTO A3" markers tie a photo to that grid row).
 - Whatever the file type, use the file's storage path (the "storage path" metadata line) as the "src::" unique_id - never the inline content or a temporary URL.
 - TABULAR data (any spreadsheet - .csv/.tsv/.xlsx/.xls/.ods, or sheet-like rows): you MUST save EVERY data row as its own record (ONE record per row) with that row's actual column values in the record's "data", keyed by the header names, in a dedicated table (e.g. "spreadsheet_rows"). Do NOT summarize, sample only a few rows, or save just file metadata - index the whole sheet, paging through it with readFileContent when it is large. Make MULTIPLE postRecords calls in batches (e.g. 30-50 rows per call) rather than one oversized call. This per-row completeness OVERRIDES brevity. ALSO save one file-level summary record (file name, sheet name(s), column headers, total row count, overall summary) - this is the record that carries the file's "src::" unique_id - and link EVERY per-row record to it via reference (set each row record's reference to that src:: file record; the row records themselves do NOT carry a src:: unique_id). The per-row records AND this reference linkage are BOTH mandatory: the linkage is what lets the whole sheet be found and cleaned up together when the file is re-indexed.
 - EPUB / e-books / long-form books (.epub or any book-length prose, provided inline in reading order with chapter headings preserved): you MUST save ONE record per CHAPTER (or, when chapters are unclear, per major section/topic) in a dedicated table (e.g. "book_chapters") - never collapse the whole book into a single record. Each chapter record's "data" must capture the chapter title plus its order/number AND a substantive summary of that chapter's content (key events, arguments, characters, places, concepts, terms, notable quotes). Apply AS MANY relevant tags as possible to EVERY chapter record (characters, locations, themes, topics, key concepts, key terms, dates, named entities) so the book is easy to SEARCH and cross-reference later - this is the whole point. ALSO save one book-level record (title, author, language, overall summary, chapter list / table of contents, genre/subjects) and link each chapter record to it via reference. This per-chapter completeness OVERRIDES brevity; human-readable summaries only, never raw/binary bytes.
-- This is a background indexing task: do ALL the MCP saving FIRST, never reply mid-task, and never ask the user questions. Always use the MCP tools to save what you learn - be exhaustive about meaning (and, for tabular data, about every row). SAVE AS YOU GO: persist each window's records before reading the next, so progress is never lost. If the file is so large you cannot finish in one turn, still save everything you have read so far and note the last cursor/page you reached; a follow-up will continue from there. Never store raw or binary bytes (base64, blobs); describe them in human-readable text instead.
+- This is a background indexing task: do ALL the MCP saving FIRST, never reply mid-task, and never ask the user questions. Always use the MCP tools to save what you learn - be exhaustive about meaning (and, for tabular data, about every row). SAVE AS YOU GO: persist each window's records before reading the next, so progress is never lost. If the file is so large you cannot finish in one turn, still save everything you have read so far; a follow-up pass will automatically continue from where you stopped. Never store raw or binary bytes (base64, blobs); describe them in human-readable text instead.
+- COMPLETION SIGNAL: only when you have fully read and saved the ENTIRE file (for readFileContent files: reached "END OF FILE"; for PDFs: the embedded page-image note said it was the LAST window - with all rows/pages/items saved), end your final message with the token INDEXING_COMPLETE on its own line. If you did NOT finish the whole file (more rows/pages remain), do NOT write that token - leaving it out is how the system knows to run another pass to continue.
 - Only AFTER every save is done, send exactly ONE final message summarizing what you indexed - never just "Indexing complete", and never a raw/base64/binary value or a large pasted dump. Keep it to a few factual sentences or a short markdown bullet list covering: the file name, its content type, each table you wrote to with its record/row count and the key columns/fields or topics captured, and anything that could not be extracted. Follow this shape - Indexed <file name> (<content type>): saved <N> records to <table(s)> capturing <key columns/fields or topics>; could not extract: <gaps, or none>.`;
 
 	if (serviceDescription) {

package/src/engine/prompts/indexing_user_message.ts

@@ -36,6 +36,12 @@ export type BuildIndexingUserMessageOptions = {
 	 * web_fetch for this file. Takes precedence over `inlineContentPlaceholder`.
 	 */
 	inlineContent?: string;
+	/**
+	 * Spreadsheet or PDF: read by PAGING through the readFileContent tool (grid rows +
+	 * embedded photos / rendered scanned pages), not inline and not by web_fetch. The
+	 * message instructs the agent to page through EVERY window and datafy each.
+	 */
+	pagedRead?: boolean;
 };
 
 export function buildIndexingUserMessage(
@@ -78,5 +84,101 @@ export function buildIndexingUserMessage(
 		);
 	}
 
+	if (options?.pagedRead) {
+		// Spreadsheet / PDF: force the paging path. The agent MUST read this with the
+		// readFileContent tool (which returns the file window by window, with grid rows,
+		// embedded photos, and rendered scanned pages), NOT by fetching the URL.
+		return (
+			head +
+			`\nRead this file with the readFileContent tool, using the storage path above - do NOT fetch a URL and do NOT rely on a single sample. ` +
+			`readFileContent returns the file ONE WINDOW at a time: spreadsheets as coordinate-tagged grid rows (e.g. 'R4 A:E&I NUMBER | B:E1007'), scanned/large PDFs as rendered PAGE IMAGES, and windows may include embedded photos - LOOK at any images and datafy what they show. ` +
+			`Page through EVERY window: for each window SAVE records for its rows/items/pages (postRecords, one record per row/item), THEN if the window says MORE REMAINS call readFileContent again with the cursor it gives you. Repeat until it says END OF FILE, so the WHOLE file is indexed. ` +
+			`Do NOT stop after the first window and do NOT just write a summary. Use the storage path above for the "src::" unique_id.` +
+			(attachment.url ? `\n(A temporary URL is provided ONLY as a fallback if readFileContent fails: ${attachment.url})` : '')
+		);
+	}
+
 	return head + `- temporary URL (fetch this to read the file contents): ${attachment.url}`;
 }
+
+/**
+ * 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.
+ *
+ * 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).
+ */
+export function buildIndexingRenderMessage(
+	attachment: IndexingAttachmentInfo,
+	placeholder: string,
+	renderFrom: number,
+): string {
+	const from = Math.max(0, renderFrom || 0);
+	const src = `src::${attachment.storagePath}`;
+	const meta =
+		`File metadata:\n` +
+		`- name: ${attachment.name}\n` +
+		`- storage path: ${attachment.storagePath}\n` +
+		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '');
+
+	// Shared datafy + completion guidance. The placeholder is where the worker splices the
+	// note + rendered page images; instructions reference "the page images in this message"
+	// so they read correctly whether the images land before or after this text.
+	const datafy =
+		`\n${placeholder}\n\n` +
+		`LOOK at each rendered page image in this message and DATAFY what it shows: for EVERY page ` +
+		`call postRecords and save records - one record per row / table entry / line item visible on the page ` +
+		`(or one record for the page if it is prose), capturing every value you can read (OCR the text, read tables ` +
+		`cell by cell, describe any photos/diagrams). Use the storage path above for the "src::" unique_id.\n\n` +
+		`The note next to the images tells you whether MORE pages remain after this window. ` +
+		`If MORE remain: save this window's records and STOP - do NOT write INDEXING_COMPLETE; another pass shows the next window automatically. ` +
+		`Only when the note says this is the LAST window (you have seen the whole file) AND everything is saved, end your message with the token INDEXING_COMPLETE.`;
+
+	if (from === 0) {
+		return (
+			`A new file has just been uploaded. Index it now.\n\n` +
+			meta +
+			`\nThis is a PDF. Its pages are delivered to you as RENDERED PAGE IMAGES embedded directly in this ` +
+			`message (you do NOT need any tool, URL, or web_fetch to see them). You are shown a WINDOW of pages ` +
+			`at a time, starting at page ${from + 1}.\n` +
+			datafy
+		);
+	}
+
+	return (
+		`CONTINUE indexing a PDF whose previous pass did not finish.\n\n` +
+		meta +
+		`\nRecords for the earlier pages are ALREADY saved (they reference "${src}"). The NEXT window of ` +
+		`rendered page images (starting at page ${from + 1}) is embedded in this message. Datafy each page as ` +
+		`before and do NOT re-save pages that are already saved.\n` +
+		datafy
+	);
+}
+
+/**
+ * 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).
+ */
+export function buildIndexingContinueMessage(attachment: IndexingAttachmentInfo): string {
+	const src = `src::${attachment.storagePath}`;
+	return (
+		`CONTINUE indexing a file whose previous pass did not finish.\n\n` +
+		`File metadata:\n` +
+		`- name: ${attachment.name}\n` +
+		`- storage path: ${attachment.storagePath}\n` +
+		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
+		`\nRecords for the earlier windows/pages of this file are ALREADY saved (they reference "${src}"). ` +
+		`First call getRecords with reference "${src}" to see how far the previous pass got (the furthest page/row/window already saved). ` +
+		`Then call readFileContent with the storage path above and a CURSOR that RESUMES just after that point - do NOT start at the beginning. The cursor is derivable from what you already saved:\n` +
+		`  - PDF: the cursor is the NUMBER OF PAGES already read (0-based next page). If you saved up to page N, call readFileContent with cursor="N" to get page N+1 onward.\n` +
+		`  - Spreadsheet: the cursor is "<sheetIndex>:<nextRow>" (0-based sheet index, 1-based row). If you saved up to row R of sheet S, use cursor="S:R+1".\n` +
+		`  - Text: the cursor is the character offset already read.\n` +
+		`Index the REMAINING windows - one record per row/item, looking at any page images or embedded photos - saving as you go until readFileContent reports END OF FILE. ` +
+		`Do NOT re-save windows that are already saved. ` +
+		`Use the storage path above for the "src::" unique_id. When the ENTIRE file is finally indexed, end your message with the token INDEXING_COMPLETE.`
+	);
+}

package/src/engine/requests.ts

@@ -10,8 +10,8 @@
  *                                    state that stays in the consumer, not here;
  *                                    only the BgTaskEntry TYPE lives here)
  */
-import { buildIndexingSystemPrompt, buildIndexingUserMessage } from './prompts';
-import { isServerExtractable, makeExtractPlaceholder, type ExtractDirective, type FileUrlDirective } from './office';
+import { buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingContinueMessage, buildIndexingRenderMessage } from './prompts';
+import { isServerExtractable, isPagedReadFile, isImageVisionFile, makeExtractPlaceholder, makeRenderPlaceholder, RENDER_PAGES_PER_WINDOW, type ExtractDirective, type FileUrlDirective } from './office';
 import { chatEngineConfig, pollOpt } from './config';
 
 export const ANTHROPIC_MESSAGES_API_URL = 'https://api.anthropic.com/v1/messages';
@@ -442,16 +442,56 @@ export type AttachmentSaveInfo = {
 	 * takes precedence over server-side office extraction / web_fetch.
 	 */
 	parsedContent?: string;
+	/**
+	 * True for a RESUME pass: a previous indexing pass could not finish this (large)
+	 * file, so continue it - always via readFileContent paging, with a "continue"
+	 * message telling the agent to resume from where the saved records leave off.
+	 */
+	continueIndexing?: boolean;
+	/**
+	 * For an image-vision file (PDF), the 0-based PAGE the render window should start at.
+	 * The worker renders [renderFrom, renderFrom+RENDER_PAGES_PER_WINDOW) and injects them
+	 * as image blocks; the resume loop advances this by a window each pass.
+	 */
+	renderFrom?: number;
 };
 
+// RESUME pass: continue indexing a large file a previous pass could not finish. Same
+// dispatch as notifyAgentSaveAttachment, but forced onto the paging path with a
+// "continue from where the saved records leave off" message.
+export async function notifyAgentContinueIndexing(info: AttachmentSaveInfo) {
+	return notifyAgentSaveAttachment({ ...info, continueIndexing: true });
+}
+
 // Background "save into knowledge" call (not a chat turn). A client-parsed file
 // (parser plugin) is inlined directly; otherwise office files get the
 // _skapi_extract directive + a placeholder, and everything else gets a URL.
 export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 	const { platform, service, owner, attachment, parsedContent } = info;
 
+	// A CONTINUE pass resumes a large file that a previous pass could not finish.
+	const continuing = !!info.continueIndexing;
+
+	// VISION files (PDFs) are delivered as rendered page IMAGES injected into the message by
+	// the worker (`_skapi_render`), because tool-result images render on neither provider.
+	// Both the first pass and every resume pass use this; renderFrom advances the page window.
+	const visionFile = !parsedContent && isImageVisionFile(attachment.name, attachment.mime);
+	const renderFrom = Math.max(0, info.renderFrom || 0);
+	const renderPlaceholder = visionFile ? makeRenderPlaceholder(attachment.storagePath) : undefined;
+	const skapiRender = visionFile && renderPlaceholder
+		? {
+			_skapi_render: [
+				{ path: attachment.storagePath, from: renderFrom, count: RENDER_PAGES_PER_WINDOW, placeholder: renderPlaceholder, name: attachment.name, mime: attachment.mime },
+			],
+		}
+		: {};
+
+	// Spreadsheets are read by PAGING through readFileContent (grid rows), NOT inlined - so
+	// they skip the inline server-extract and the agent is told to page the whole file.
+	const pagedRead = !visionFile && (continuing || (!parsedContent && isPagedReadFile(attachment.name, attachment.mime)));
+
 	// Client-parsed content wins over server-side extraction.
-	const serverExtract = !parsedContent && isServerExtractable(attachment.name, attachment.mime);
+	const serverExtract = !visionFile && !continuing && !parsedContent && !pagedRead && isServerExtractable(attachment.name, attachment.mime);
 	const placeholder = serverExtract ? makeExtractPlaceholder(attachment.storagePath) : undefined;
 	const extractContent: ExtractDirective[] | undefined =
 		serverExtract && placeholder
@@ -460,14 +500,20 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 	const skapiExtract =
 		extractContent && extractContent.length ? { _skapi_extract: extractContent } : {};
 
-	const userMessage = buildIndexingUserMessage(
-		attachment,
-		parsedContent
-			? { inlineContent: parsedContent }
-			: placeholder
-				? { inlineContentPlaceholder: placeholder }
-				: undefined,
-	);
+	const userMessage = (visionFile && renderPlaceholder)
+		? buildIndexingRenderMessage(attachment, renderPlaceholder, renderFrom)
+		: continuing
+			? buildIndexingContinueMessage(attachment)
+			: buildIndexingUserMessage(
+				attachment,
+				parsedContent
+					? { inlineContent: parsedContent }
+					: placeholder
+						? { inlineContentPlaceholder: placeholder }
+						: pagedRead
+							? { pagedRead: true }
+							: undefined,
+			);
 
 	const systemPrompt = buildIndexingSystemPrompt({
 		service,
@@ -494,6 +540,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 				model: resolvedModel,
 				max_output_tokens: MAX_TOKENS,
 				...skapiExtract,
+				...skapiRender,
 				input: [
 					{ role: 'system', content: systemPrompt },
 					{
@@ -541,6 +588,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 			model: resolvedModel,
 			max_tokens: MAX_TOKENS,
 			...skapiExtract,
+			...skapiRender,
 			system: [
 				{
 					type: 'text',
@@ -679,8 +727,25 @@ export type BgTaskEntry = {
 	size?: number;
 	status: 'running' | 'pending';
 	poll: ((opts: { latency: number }) => Promise<any>) | undefined;
+	/** How many CONTINUE passes have already run for this file (resume-across-passes). */
+	resumePass?: number;
 };
 
+// Token the indexing agent appends to its final message ONLY when it has fully read and
+// saved the whole file. Its ABSENCE is what tells the client to run another CONTINUE pass.
+export const INDEXING_COMPLETE_MARKER = 'INDEXING_COMPLETE';
+// Cap on CONTINUE passes per file, so a file the agent can never mark complete (or a
+// pathological loop) stops instead of re-dispatching forever. The text/grid paging path
+// reads MANY windows within a single pass (the agent loops readFileContent in one turn), so
+// a small cap suffices.
+export const MAX_INDEXING_RESUME_PASSES = 6;
+// The VISION path (rendered PDF pages) can only advance ONE page-window per pass, because the
+// worker injects a single window of images into each request. A big scanned PDF therefore
+// needs one pass PER window (pages / RENDER_PAGES_PER_WINDOW), so it gets a much higher cap.
+// The loop still terminates naturally when the agent reaches the last window (it appends
+// INDEXING_COMPLETE); this cap is only the backstop for a doc larger than it covers.
+export const MAX_VISION_RESUME_PASSES = 40;
+
 export async function getChatHistory(
 	params: { service?: string; owner?: string; platform: 'claude' | 'openai'; queue?: string },
 	fetchOptions: Record<string, any>,

package/src/engine/session.ts

@@ -21,6 +21,10 @@ import {
 	callClaudeWithPublicMcp,
 	callOpenAIWithPublicMcp,
 	notifyAgentSaveAttachment,
+	notifyAgentContinueIndexing,
+	INDEXING_COMPLETE_MARKER,
+	MAX_INDEXING_RESUME_PASSES,
+	MAX_VISION_RESUME_PASSES,
 	extractClaudeText,
 	extractOpenAIText,
 	getChatHistory,
@@ -30,6 +34,7 @@ import {
 	OPENAI_RESPONSES_API_URL,
 	type BgTaskEntry,
 } from './requests';
+import { isPagedReadFile, isImageVisionFile, RENDER_PAGES_PER_WINDOW } from './office';
 import { isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, getErrorMessage } from './errors';
 import { buildBoundedChatMessages } from './budget';
 import { createInlineLinkRegex } from './links';
@@ -736,6 +741,8 @@ export class ChatSession {
 		var isErr = isErrorResponseBody(response);
 		var answer = isErr ? getErrorMessage(response)
 			: ((platform === 'openai' ? extractOpenAIText(response) : extractClaudeText(response)) || '').trim();
+		// Hide the internal indexing-completion marker from the displayed summary.
+		if (!isErr && answer) answer = answer.split(INDEXING_COMPLETE_MARKER).join('').trim();
 		var idx = this.state.messages.findIndex(function (m) { return m.isPending && m._serverItemId === itemId; });
 		if (idx !== -1) {
 			// A bg "Indexing:" turn pushes a user bubble (isPendingInProcess) ALONGSIDE
@@ -806,8 +813,10 @@ export class ChatSession {
 			if (!self.historyItemPolls.has(entry.id) && typeof entry.poll === 'function') {
 				self.historyItemPolls.set(entry.id, true);
 				var capturedId = entry.id, capturedPlat = plat;
+				var capturedEntry = entry;
 				entry.poll({ latency: POLL_INTERVAL }).then(function (response: any) {
 					self.handleHistoryItemResolution(capturedId, response, capturedPlat);
+					self.maybeResumeIndexing(capturedEntry, response, capturedPlat);
 				}).catch(function (err: any) {
 					self.historyItemPolls.delete(capturedId);
 					var isNotExists = err && (err.code === 'NOT_EXISTS' || (err.body && err.body.code === 'NOT_EXISTS'));
@@ -826,6 +835,62 @@ export class ChatSession {
 		this.promoteNextBgQueuedToRunning();
 	}
 
+	// Resume-across-passes: if a background INDEXING task for a paged file (spreadsheet or
+	// PDF) finished WITHOUT the completion marker, the agent ran out of room before reading
+	// the whole file - dispatch a CONTINUE pass (up to a cap) that resumes from where the
+	// already-saved records leave off. Additive + guarded so it never loops forever and
+	// never breaks the resolution path.
+	maybeResumeIndexing(entry: BgTaskEntry, response: any, platform: string): void {
+		var self = this;
+		try {
+			if (!entry || !entry.storagePath) return;
+			if (!isPagedReadFile(entry.filename, entry.mime)) return;
+			if (isErrorResponseBody(response)) return; // a failed pass is not "incomplete"
+			var answer = (platform === 'openai' ? extractOpenAIText(response) : extractClaudeText(response)) || '';
+			if (answer.indexOf(INDEXING_COMPLETE_MARKER) !== -1) return; // fully indexed
+			var pass = (entry.resumePass || 0) + 1;
+			// Vision (rendered PDF pages) advances one window per pass, so it needs a much
+			// higher cap than the text/grid path (which reads many windows per pass).
+			var isVision = isImageVisionFile(entry.filename, entry.mime);
+			var maxPasses = isVision ? MAX_VISION_RESUME_PASSES : MAX_INDEXING_RESUME_PASSES;
+			if (pass > maxPasses) return; // give up after the cap
+			var id = this.host.getIdentity();
+			if (!id || id.platform === 'none' || id.serviceId !== entry.serviceId) return;
+			// VISION files (PDFs) resume by ADVANCING the rendered page window: pass N reads
+			// pages [N*WINDOW, (N+1)*WINDOW). Other paged files resume via a derived cursor
+			// (the continue message tells the agent to resume from the furthest saved record).
+			var renderFrom = isVision ? pass * RENDER_PAGES_PER_WINDOW : undefined;
+			notifyAgentContinueIndexing({
+				platform: id.platform as 'claude' | 'openai',
+				model: id.model,
+				service: id.serviceId,
+				owner: id.owner,
+				userId: id.userId || id.serviceId,
+				serviceName: id.serviceName,
+				serviceDescription: id.serviceDescription,
+				renderFrom: renderFrom,
+				attachment: {
+					name: entry.filename,
+					storagePath: entry.storagePath,
+					mime: entry.mime,
+					size: entry.size,
+					url: '',
+				},
+			}).then(function (ack: any) {
+				if (ack && typeof ack.id === 'string') {
+					self.bgTaskQueue.push({
+						serviceId: id.serviceId, platform: id.platform as 'claude' | 'openai', id: ack.id,
+						filename: entry.filename, storagePath: entry.storagePath,
+						isReindex: entry.isReindex, mime: entry.mime, size: entry.size,
+						status: ack.status === 'running' ? 'running' : 'pending',
+						poll: ack.poll, resumePass: pass,
+					});
+					self.drainBgTaskQueue();
+				}
+			}, function (e: any) { console.error('[chat-engine] resume-indexing dispatch failed', e); });
+		} catch (e) { /* best-effort: resume must never break bg-task resolution */ }
+	}
+
 	// --- history fetch + pagination --------------------------------------
 	// Initial load (fetchMore=false) replaces the list (with in-flight rescue +
 	// cancelled-merge) and attaches polls to running/pending items; pagination