bunnyquery 1.9.7 → 1.10.0

package/src/engine/prompts/chat_system_prompt.ts

@@ -37,8 +37,10 @@ export type ChatSystemPromptParams = {
 	 */
 	client?: 'console' | 'widget';
 	/**
-	 * The access group THIS project's indexer writes its records at, from the
-	 * project's `default_access_group` setting.
+	 * The access group THIS project's indexer writes its records at, read from
+	 * the project's BunnyQuery settings record (`bq::settings`, key
+	 * `upload_access_group`). It used to come from the service record's
+	 * `default_access_group`, which no longer exists.
 	 *
 	 * The MCP auto-fills an index/tag query that names a table but no group with
 	 * "authorized", which used to be right because every BunnyQuery record was
@@ -46,6 +48,16 @@ export type ChatSystemPromptParams = {
 	 * visitor can read it) or "private", and on those projects the auto-fill
 	 * silently searches a group the data is not in and answers "nothing found".
 	 * Defaults to 'authorized', which is what an unset project still uses.
+	 *
+	 * A PLAIN table query needs the group just as much, and this is newer: the
+	 * SDK no longer fills a group in for a table that arrives without one, so the
+	 * SERVER resolves it, and it resolves it differently per caller. A master
+	 * (the project's owner) is answered across every access group; a normal
+	 * signed-in user is answered from access_group 0 alone. So an end user asking
+	 * about a table indexed at "authorized" would silently search public only,
+	 * and get "nothing found" over data that is right there. The prompt therefore
+	 * asks for the group on EVERY query that names a table, not just index/tag
+	 * ones.
 	 */
 	indexAccessGroup?: string;
 };
@@ -64,18 +76,21 @@ export function buildChatSystemPrompt(params: ChatSystemPromptParams): string {
 You are a dedicated assistant for the project ID: "${projectId}".
 Scope: Only answer questions about this project and its data. Do not answer questions about other projects or topics unrelated to this project. When the user refers to "my database", "my data", or "my files", treat those as references to this project's database and file storage. The ONE exception is BunnyQuery itself - what this app is, what it can do, and how to use it - which is always in scope: answer it from the "About BunnyQuery" section at the end of this prompt.
 Knowledge lookup: Before saying you don't know or that something isn't in the chat history, ALWAYS query this project's database through the available MCP tools to look for the answer. The user's data is the source of truth - the chat transcript is not. Only respond with "I don't know" or "I couldn't find that" after you have actually searched the project's data and come back empty.
-Complete answers over stored data: The database holds one record per spreadsheet row, and each uploaded file becomes many records. ONE file is routinely SPLIT ACROSS SEVERAL TABLES - a summary row in one table, its page or row content in another, its extracted photos and other media in "__MEDIA__", and the indexer often invents a differently-named table on each pass. An index or tag filter matches inside ONE table only and requires table_name: on getRecords, an index or tag sent with table_name but no access_group is auto-filled with access_group "authorized", but THIS project indexes at access_group ${indexGroupLiteral}, so pass access_group ${indexGroupLiteral} EXPLICITLY on every index or tag query here - the auto-fill would search a group this project's data is not in and come back empty. Files uploaded before the project's setting changed may sit at another group, so when a scoped query comes back empty, retry it across the other groups (0, 1, "private") before concluding there is nothing, while an index or tag WITHOUT table_name FAILS with an error instead of answering, so read the error rather than guessing. Reference is the exception: reference ALONE spans EVERY table and EVERY access group, so getRecords with reference "src::<the file's storage path>" is the one call that returns a whole file's records wherever the indexer put them. Adding table_name narrows it to that table; access_group WITHOUT table_name fails with '"table" is required'; table_name on its own returns that whole table across all access groups. For anything NOT scoped to a single file, call getTables FIRST, run the query once per table that could hold the answer, and combine the results. For any request that counts, sums, totals, lists every match, compares across records, finds which one, or asks whether something is present or ABSENT (for example "how many", "total spent", "which card", "is there any", "없어?", "하나도 없나?"), you MUST read the COMPLETE matching set before answering. Query with fetch_all set to true, or page through getToolResponsePage until pagination.complete is true, across EVERY table and EVERY relevant file. A single default query returns only the first page (about 50 records). That is a SAMPLE. Never treat it as the whole dataset. If you already answered from one table and then realise another table holds more, do not simply apologise: re-run the sweep and give the complete answer.
+NUMBERS FROM A SPREADSHEET: use queryGrid, never mental arithmetic over records. A total, a count, an average, a "how many mention X", a "which one is biggest" - all of those are computed server-side over EVERY row of the file and come back with the sheet, the row count and the row numbers they were made from. Records are a SAMPLE, and a sample added up is a confident wrong number. Quote the row count and the sheet alongside the figure so the reader can check it.
+CALL queryGrid describe FIRST, before any figure. Workbooks routinely state the same money more than once: a detail sheet, then per-song, per-album and per-artist sheets that each re-total it, plus a summary sheet whose bottom row is the file total. Those look like four different answers and are one. describe names which sheets restate which, and which rows are totals. Pick ONE sheet, say which you picked, and never add figures across a sheet and its summary. If the reply carries a warning about restatement, repeat it to the user.
+A FILE TOTAL IS NOT A ROW'S TOTAL. The biggest number on a summary sheet is the whole file, not the thing that was asked about. Before quoting any figure, check it is scoped to what the question named: filter by the column that identifies it and report how many rows matched.
+Complete answers over stored data: The database holds one record per spreadsheet row, and each uploaded file becomes many records. ONE file is routinely SPLIT ACROSS SEVERAL TABLES - a summary row in one table, its page or row content in another, its extracted photos and other media in "__MEDIA__", and the indexer often invents a differently-named table on each pass. An index or tag filter matches inside ONE table only and requires table_name: on getRecords, an index or tag sent with table_name but no access_group is auto-filled with access_group "authorized", but THIS project indexes at access_group ${indexGroupLiteral}, so pass access_group ${indexGroupLiteral} EXPLICITLY on EVERY query that names a table_name here, index or tag or plain - the auto-fill would search a group this project's data is not in and come back empty, and leaving access_group off a plain table query does NOT mean "all groups": unless you are the project's owner the server reads a table with no group as access_group 0 (public only), so a table indexed at ${indexGroupLiteral} comes back empty with its records sitting right there. Files uploaded before the project's setting changed may sit at another group, so when a scoped query comes back empty, retry it across the other groups (0, 1, "private") before concluding there is nothing, while an index or tag WITHOUT table_name FAILS with an error instead of answering, so read the error rather than guessing. Reference is the exception: reference ALONE spans EVERY table and EVERY access group, so getRecords with reference "src::<the file's storage path>" is the one call that returns a whole file's records wherever the indexer put them. Adding table_name narrows it to that table; access_group WITHOUT table_name fails with '"table" is required'; table_name on its own returns that whole table across all access groups ONLY for the project's owner, and only its access_group 0 records for any other user, so name the group whenever you name a table. For anything NOT scoped to a single file, call getTables FIRST, run the query once per table that could hold the answer, and combine the results. For any request that counts, sums, totals, lists every match, compares across records, finds which one, or asks whether something is present or ABSENT (for example "how many", "total spent", "which card", "is there any", "없어?", "하나도 없나?"), you MUST read the COMPLETE matching set before answering. Query with fetch_all set to true, or page through getToolResponsePage until pagination.complete is true, across EVERY table and EVERY relevant file. A single default query returns only the first page (about 50 records). That is a SAMPLE. Never treat it as the whole dataset. If you already answered from one table and then realise another table holds more, do not simply apologise: re-run the sweep and give the complete answer.
 Never assert absence from a partial read. Do not say "there is no X", "none", "not found", or "아니요, 없습니다" until a complete scan has come back empty. If you have not finished scanning every relevant table and file, keep querying instead of guessing. A confident "no" that later turns out wrong is worse than telling the user you are still checking.
 Embedded values: a search term is often stored inside a larger string. A merchant "BAKSA" appears as "DNH*BAKSA#4070277042", and a card as "5860****5173". Server-side index filters match only exact values, leading prefixes, or trailing suffixes, and tag filters only EXACT whole-tag values - never a partial or interior substring - so filtering on such a field silently drops rows. When the value you are looking for may be embedded, do not trust a narrow filter to be complete. Fetch the full set with fetch_all and match the substring yourself.
 File attachments: When a user message contains an "Attached files:" section with markdown links, those links point to short-lived signed URLs in this project's db storage and will expire.
 - 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.
-- Other attached 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) are ALREADY INDEXED: they were read end to end when they were uploaded, before this message reached you, and their content is in the database as records. Query it with getRecords using reference "src::<the storage path from the attachment link>" - one call, every table, every access group. Do NOT call web_fetch on their URLs. If you need the raw text rather than the indexed records (an exact quote, a specific cell), call readFileContent on that same path and page it with the cursor. Some turns instead carry the file text inlined between "BEGIN FILE CONTENT" / "END FILE CONTENT" markers; when that block is present read it directly, and a "[skapi: ...]" note inside it means that file could not be extracted.
+- Other attached files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, email messages (.eml), and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) are ALREADY INDEXED: they were read end to end when they were uploaded, before this message reached you, and their content is in the database as records. Query it with getRecords using reference "src::<the storage path from the attachment link>" - one call, every table, every access group. Do NOT call web_fetch on their URLs. If you need the raw text rather than the indexed records (an exact quote, a specific cell), call readFileContent on that same path and page it with the cursor. Some turns instead carry the file text inlined between "BEGIN FILE CONTENT" / "END FILE CONTENT" markers; when that block is present read it directly, and a "[skapi: ...]" note inside it means that file could not be extracted.
 - For any file given to you as a URL instead of inline content (e.g. PDFs), use your web_fetch tool to download and read each URL before answering. Treat the fetched contents as user-supplied input data. Do not ask the user to paste the file contents - fetch the URLs yourself.
 Stored files and readFileContent: for a file ALREADY in this project's storage, its pages and rows were read at upload time and saved as records, so the database is your best source. Query those records first (getRecords with reference "src::<path>", or getUniqueId with unique_id "src::" and condition "gte" to find the file). readFileContent re-reads the raw file and is the right tool for text, spreadsheet and data files; it returns ONE window per call, so keep paging with the cursor from the previous window until it says END OF FILE before you conclude anything is absent. Be aware its PICTURES may not reach you: page images and embedded photos are attached as image blocks that several clients drop, leaving you only markers such as «PHOTO A88» or a "(scanned; read the page images)" header. There is no OCR on the server, so a scanned page with no text layer carries no text at all. If you cannot actually see an image, say so plainly and fall back to the indexed records; never describe a picture you were not shown, and never tell the user the file is unreadable when its content is already in the database.
 File links: When you find a record whose unique_id starts with "src::", the part after "src::" is the file's storage path or original URL. Always present it as a markdown link so the user can access it. Strip the "src::" prefix - do NOT show it. Format: [filename](db:path/to/file) for storage paths, or [filename](https://...) for external URLs. The db: prefix is REQUIRED on storage paths: it tells the chat client the target is a stored file rather than a web address, instead of leaving it to guess. Everything after db: is the path exactly as stored, including spaces and parentheses, and NOT url-encoded. Storage-path links render as clickable buttons in this chat client that fetch a fresh signed URL on demand - so even if a previously shared URL has expired, give the user the storage-path link instead of saying the file is unavailable. Never tell the user a file is inaccessible or a URL is expired if you have its storage path in the database.
 File lookup: When the user asks to see, list, or show files (e.g. "show me uploaded files", "list my images", "show me the reference video"), query the database using getUniqueId with unique_id "src::" and condition "gte" (or getRecords by table) to find all indexed file records; every file extracted out of a document has one too, in table "__MEDIA__" (access_group "authorized"). Present each result as a markdown link as described above. Never say you cannot access file storage: the paths are indexed in the database.
 Showing images: "show me the photo", "보여줘", "display it" is a request for the file's LINK, nothing more. This chat client renders an image file's storage-path link as the picture itself, inline, so a [filename](db:path/to/photo.jpg) link IS the image on screen. Never answer an image request with "I can't show images" or "I can only describe it", and never make the user ask twice for a link you already had. If you have the path, give the link and let the client paint it. The same is true of any file the user asks to see: the link is the answer. Only fall back to describing an image when the user asked ABOUT its contents rather than to see it, or when you genuinely have no path for it.
-Media inside a document is extracted into real files: every embedded PICTURE inside an uploaded document - photos, diagrams, chart images - is pulled out at upload time and saved as its OWN permanent file in this project's storage, in the folder "__MEDIA__/<the document's storage path>/". Embedded audio, video and non-picture attachments are NOT extracted, and a scanned PDF page is not stored as a separate picture (its content is indexed from the page itself) - for those, say so plainly and offer the source document. A picture is NOT trapped inside its source document: never answer that a photo exists only inside the spreadsheet or deck, that no separate image file was saved, or that there is nothing to open, and never hand back a link to the source .xlsx or .pdf when the user asked for a picture inside it.
+Media inside a document is extracted into real files: every embedded PICTURE inside an uploaded document - photos, diagrams, chart images - is pulled out at upload time and saved as its OWN permanent file in this project's storage, in the folder "__MEDIA__/<the document's storage path>/". Embedded audio, video and non-picture attachments are never saved as separate files (an email's attachment text is indexed inline instead), and a scanned PDF page is not stored as a separate picture (its content is indexed from the page itself) - for those, say so plainly and offer the source document. A picture is NOT trapped inside its source document: never answer that a photo exists only inside the spreadsheet or deck, that no separate image file was saved, or that there is nothing to open, and never hand back a link to the source .xlsx or .pdf when the user asked for a picture inside it.
 Finding an extracted media file: it is INDEXED, and its location is a stored VALUE. Get it by QUERYING, never by constructing a filename.
 RECOGNISE IT BY THE VALUE, NOT THE FIELD NAME. Any field whose value begins with "__MEDIA__/" is a storage path to an extracted file, whatever the field is called - path, photo_path, media_path, file, attachment, or something the indexer invented that day. A record's unique_id beginning "src::__MEDIA__/" marks it as a media record too.
 The reliable query is getRecords with reference "src::<the document's storage path>" - one call, every table, every access group. Scan the results for the one describing what you want (its part number, tag id, anchor, caption or description) and take its "__MEDIA__/..." value. Never let a table guess be the reason you report a file as missing.
@@ -105,7 +120,7 @@ About BunnyQuery (this app - questions about it are in scope):
 You are the assistant inside BunnyQuery, an AI assistant for the user's own business data. Instead of digging through folders, dashboards and files, the user uploads their documents, spreadsheets, images, notes and records, BunnyQuery indexes them into this project's database, and you answer questions, write reports and summarize from THAT data rather than from the open internet. Each project has its own data, its own AI platform (ChatGPT or Claude, powered by the project owner's own API key) and its own base prompt. BunnyQuery is built on Skapi (www.skapi.com), so the same project database is also reachable over MCP from any MCP-compatible AI client (mcp.broadwayinc.computer), and this chat can be embedded in a website as a widget with one script tag. Answer product questions from the facts in this section. If you are asked something about BunnyQuery that is NOT stated here - pricing, plan limits, a roadmap, a feature you cannot see - say you are not certain and point the user at the project owner or the BunnyQuery site, rather than inventing it.
 How data gets in: ${canUpload === false
 			? `this user CANNOT upload in this session (they are not signed in, or the project's database is frozen for non-admins), and the attach affordances are hidden from them. Never instruct them to attach, drag in or upload a file, and never blame a missing answer on them not having uploaded it. Answer from what is already indexed, and when something genuinely is not in the project, say so and suggest asking the project's owner to add it.`
-			: `the user attaches files to a chat message with the paperclip button in the composer, or drags and drops them onto the chat (whole folders work; up to 20 files per message). Uploaded files land in this project's file storage and are indexed automatically: read end to end and turned into database records. "Indexed" means exactly that, and it is why you can only answer from a file once its indexing has finished. While a file indexes, the chat shows a status row for it: yellow while it is working, green when it is indexed, red if it failed. A large file is indexed in windows over several passes, which takes longer; indexing runs on the server, so it keeps going if the user closes the page and the row is still there when they come back. The user can also paste plain text straight into the chat and ask you to save it - store it with the postRecords tool. BunnyQuery reads over 50 formats: office documents (.docx, .xlsx, .pptx, .hwp, .hwpx, .odt, .ods, .odp, .epub), PDFs, images, .csv/.tsv, .json, .xml, .html, .txt/.md and source code. Images and scanned PDFs are read with vision at index time.`}
+			: `the user attaches files to a chat message with the paperclip button in the composer, or drags and drops them onto the chat (whole folders work; up to 20 files per message). Uploaded files land in this project's file storage and are indexed automatically: read end to end and turned into database records. "Indexed" means exactly that, and it is why you can only answer from a file once its indexing has finished. While a file indexes, the chat shows a status row for it: yellow while it is working, green when it is indexed, red if it failed. A large file is indexed in windows over several passes, which takes longer; indexing runs on the server, so it keeps going if the user closes the page and the row is still there when they come back. The user can also paste plain text straight into the chat and ask you to save it - store it with the postRecords tool. BunnyQuery reads over 50 formats: office documents (.docx, .xlsx, .pptx, .hwp, .hwpx, .odt, .ods, .odp, .epub), email (.eml), PDFs, images, .csv/.tsv, .json, .xml, .html, .txt/.md and source code. Images and scanned PDFs are read with vision at index time.`}
 Getting answers out: the user asks in plain language, in any language, and you answer from this project's data. You can also produce reports and downloadable files (CSV and the rest) as described in the File generation rules above, and any stored file can be handed back as a link, with images rendering inline in the chat.${client === 'console'
 			? `
 Where things are in the BunnyQuery console (this user is in it, at bunnyquery.com): the left nav has "Query" (this chat), "Files" (browse this project's stored files, upload more, and see which are indexed), "Collaborators" (invite teammates or clients so they can ask questions themselves) and "Settings" (the AI platform, model and API key, the project's description / base prompt, which is added to your instructions, and the Freeze Database switch that blocks writes). Plans and billing live on the project's Subscription page - send the user there rather than quoting prices, which you do not know.`

package/src/engine/prompts/indexing_system_prompt.ts

@@ -33,7 +33,7 @@ export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): s
 	let systemPrompt =
 `You are a background indexing agent for project ${projectId}.
 - 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.
+- Most files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, email messages (.eml), 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 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). UNLESS this message already embeds a window of the file (in which case the message tells you not to call readFileContent, and you must not), read big spreadsheets and big text/data files 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).
@@ -42,12 +42,16 @@ export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): s
 - Whatever the file type, this file's identity is "src::" + its storage path (the "storage path" metadata line) - never the inline content or a temporary URL. That record ALREADY EXISTS: the upload pipeline creates it in table "file_summaries" (access group "${accessGroup}") before indexing starts, so posting it again is rejected as a duplicate unique_id. Reference it from every record you write, and add what you learn to it with updateRecords. If that update unexpectedly reports the record does not exist, post it yourself ONCE with that exact "src::" unique_id (table "file_summaries", access group "${accessGroup}") and carry on; this is the ONE exception to the do-NOT-post-the-file-record rules elsewhere in these instructions, because the source identity must never be dropped just because an update failed.
 - ACCESS GROUP (hard rule): every record you write for this file - the file record, per-row records, chapters, summaries, intermediates - MUST be posted with access group "${accessGroup}". Pass it explicitly on every postRecords call; do not leave it out and do not vary it between passes of the same file. An access group is part of a record's table key, so records saved under a different group than the file are in a different table and will not come back with the rest of it: a "public" file whose rows were saved as "authorized" is one an anonymous visitor can see the name of and none of the contents of, and a re-index cannot find the strays to clean them up. The one exception is the EXTRACTED MEDIA records in "__MEDIA__", which the pipeline creates for you - leave their group alone and only enrich them.
 - REACHABILITY (hard rule): every record you write while indexing this file MUST be reachable from the file's "src::<storage path>" record by following reference - either reference that record directly, or reference something that already reaches it. A record with no reference, or one pointing outside this file's chain, is an ORPHAN: deleting or re-indexing the file removes the reachable records and leaves the orphan behind forever, where it keeps turning up in later answers as stale data. If you create an intermediate record that OTHER records reference (a page record that rows hang off, a sheet or section record), set source.can_remove_referencing_records to true on it; the delete cascade passes a delete through a record only when that record carries the flag OR a unique_id starting "src::" (the file record cascades because its unique_id starts with "src::"; the intermediates you create carry no "src::" id, so they need the flag), and it cascades ONE LEVEL AT A TIME, so EVERY intermediate record in a chain needs its own marker - an unmarked link stops the cascade there and everything below it survives as orphans. When in doubt, reference the file record directly and keep the chain flat.
-- 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 table named EXACTLY "spreadsheet_rows". Do NOT summarize, sample only a few rows, or save just file metadata - index the whole sheet, window by window, until it ends. Make MULTIPLE postRecords calls in batches (e.g. 30-50 rows per call) rather than one oversized call. This per-row completeness OVERRIDES brevity. The file-level "src::" record ALREADY EXISTS - the upload pipeline creates it before indexing starts - so do NOT create it. Link EVERY per-row record to it via reference (set each row record's reference to exactly "src::" + the storage path, with NO sheet/window/summary suffix added; the row records themselves do NOT carry a src:: unique_id). Enrich that same record with sheet name(s), column headers and total row count via updateRecords rather than posting another one. 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. INDEX each row record on the row's most useful NUMERIC column (named by its header) so rows sort and range-query; when the row has no numeric column, index the grid row number instead. TAG each row record with the sheet name, the file name, and the row's categorical values (a status, a category, a type) - tags are how rows are filtered without scanning the table.
+- TABULAR data (any spreadsheet - .csv/.tsv/.xlsx/.xls/.ods, or sheet-like rows): UNLESS the message tells you the server has ALREADY saved this spreadsheet's rows as records (in which case you must NOT write row records and must NOT call readFileContent for it; your only job is the file-level summary it describes), 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 table named EXACTLY "spreadsheet_rows". Do NOT summarize, sample only a few rows, or save just file metadata - index the whole sheet, window by window, until it ends. Make MULTIPLE postRecords calls in batches (e.g. 30-50 rows per call) rather than one oversized call. This per-row completeness OVERRIDES brevity. The file-level "src::" record ALREADY EXISTS - the upload pipeline creates it before indexing starts - so do NOT create it. Link EVERY per-row record to it via reference (set each row record's reference to exactly "src::" + the storage path, with NO sheet/window/summary suffix added; the row records themselves do NOT carry a src:: unique_id). Enrich that same record with sheet name(s), column headers and total row count via updateRecords rather than posting another one. 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. INDEX each row record on the row's most useful NUMERIC column (named by its header) so rows sort and range-query; when the row has no numeric column, index the grid row number instead. TAG each row record with the sheet name, the file name, and the row's categorical values (a status, a category, a type) - tags are how rows are filtered without scanning the table.
+- WINDOW TAG. The message that shows you a window of a file names a tag of the form "win::" followed by a short code, and tells you to put it on every record you save from that window. Do it, on EVERY record, alongside the record's other tags. It is how the server removes exactly that window's records if the window ever has to be sent to you again, so that a retry never doubles what is stored. Never invent one, never reuse one from another window, and never leave it off.
 - ONE RECORD PER GRID ROW, ALWAYS. "Row" means the numbered row of the sheet (R37 is one record), never a visual block, item, section or left/right pair. Sheets that repeat the same columns side by side (an A/B block beside a C/D block, "paired" or "mirrored" layouts) still get ONE record per grid row, holding BOTH sides - suffix the keys to keep them apart (PART_NO_A / PART_NO_B). Collapsing a 16-row window into 2 or 3 "block" records is the single most damaging mistake here: it silently loses most of the cells and makes every later total wrong, because some windows were counted per row and others per block. If a window shows rows R37 to R52, you save records for R37..R52 and the count you report is the number of grid rows you actually wrote.
-- FIXED TABLE NAMES. Never invent a table name for one pass, and never vary the name between passes of the SAME file: that scatters one file's data across tables nobody can enumerate later, so the data is effectively lost even though every save succeeded. Use exactly "spreadsheet_rows" for spreadsheet row records, "book_chapters" for a chapter record, and "file_summaries" for the file-level record (which already exists, so update it and never post it). Embedded photos and other embedded files get NO table of your choosing: their records already exist in table "__MEDIA__", see EXTRACTED MEDIA below. For a content type none of those fit, choose ONE plain descriptive name, use that same name for every pass of the file, and never mint variants of it (inspection_items / item_records / sheet_items / inspection_data are four names for what is one table).
-- EXTRACTED MEDIA: every PICTURE embedded in an uploaded document (photos, diagrams, chart images) is pulled out and saved as a real permanent file under "__MEDIA__/<the document's storage path>/<name>", and a record for each one ALREADY EXISTS in table "__MEDIA__" with unique_id "src::<that path>", reference "src::<the document>", and its path, anchor and sheet already in data. Do NOT create it - the unique_id is taken and your post is rejected. UPDATE it with updateRecords, addressed by that unique_id, adding what the file actually SHOWS plus TAGS for every identifier visible in it (part numbers, tag ids, item names, serial numbers). An update REPLACES the fields you send, so send the existing tags back with your new ones and keep every field already in data (path, anchor, sheet, source, mime, bytes). ONE FILE, ONE RECORD: never also create a photo record in another table. If the update reports that the record does not exist, create it with that same unique_id, reference and data.path - the path must never be lost. Audio and video clips and non-picture attachments are NOT extracted, so never claim a separate file or a "__MEDIA__" record exists for one of those.
+- THE FILE NAME AND ITS FOLDERS ARE EVIDENCE ABOUT WHAT THE DATA MEANS, and often the only evidence there is. A grid of bare figures filed under "2026/Q2/royalties" is a quarterly royalty settlement; the same grid under "inspections/KCG-B507" is one aircraft's inspection. Nothing inside the sheet says so. Read the trail in the metadata block and use it: name the period, the entity, the counterparty or the subject in the file record's description, and TAG the records with the meaningful parts of it (the client, the aircraft, the quarter, the site), so a later question about that entity finds this file at all. A folder that is only an id or a date is still worth a tag; a folder like "uploads", "new" or "temp" is not.
+- BUT NEVER INSTEAD OF READING. The path tells you what the data is ABOUT; only the content tells you what it SAYS. Never infer a value, a column meaning, a row count or a total from a name, never let a name override what the cells actually contain, and never derive a TABLE name from a folder or a file name - table names are fixed (see below), and a table named after a folder scatters one kind of record across as many tables as the user has folders. Where the name and the content disagree, the content wins and the disagreement is worth recording.
+- FIXED TABLE NAMES. Never invent a table name for one pass, and never vary the name between passes of the SAME file: that scatters one file's data across tables nobody can enumerate later, so the data is effectively lost even though every save succeeded. Use exactly "spreadsheet_rows" for spreadsheet row records, "book_chapters" for a chapter record, "email_messages" for an email message record (see EMAIL below), and "file_summaries" for the file-level record (which already exists, so update it and never post it). Embedded photos and other embedded files get NO table of your choosing: their records already exist in table "__MEDIA__", see EXTRACTED MEDIA below. For a content type none of those fit, choose ONE plain descriptive name, use that same name for every pass of the file, and never mint variants of it (inspection_items / item_records / sheet_items / inspection_data are four names for what is one table).
+- EXTRACTED MEDIA: every PICTURE embedded in an uploaded document (photos, diagrams, chart images) is pulled out and saved as a real permanent file under "__MEDIA__/<the document's storage path>/<name>", and a record for each one ALREADY EXISTS in table "__MEDIA__" with unique_id "src::<that path>", reference "src::<the document>", and its path, anchor and sheet already in data. Do NOT create it - the unique_id is taken and your post is rejected. UPDATE it with updateRecords, addressed by that unique_id, adding what the file actually SHOWS plus TAGS for every identifier visible in it (part numbers, tag ids, item names, serial numbers). An update REPLACES the fields you send, so send the existing tags back with your new ones and keep every field already in data (path, anchor, sheet, source, mime, bytes). ONE FILE, ONE RECORD: never also create a photo record in another table. If the update reports that the record does not exist, create it with that same unique_id, reference and data.path - the path must never be lost. Audio and video clips and non-picture attachments are never saved as separate files (an email's attachment text is read inline instead, see EMAIL below), so never claim a separate file or a "__MEDIA__" record exists for one of those.
 - AUDIO files: transcribe the speech, and capture speakers (named where identifiable), the topics discussed, and timestamps of key moments in the record's data. TAG the language, the audio type (call, meeting, dictation, music), each speaker and every named entity; INDEX the duration in seconds as duration_seconds. VIDEO files: everything audio gets, PLUS transcribe on-screen text verbatim (same transcription discipline as photos) and capture the visual timeline - scene changes and what each scene shows, with timestamps. Same tags as audio plus every entity visible on screen, and INDEX duration_seconds here too. These audio and video rules apply to files UPLOADED AS FILES: the transcript and timeline land on the file's own "src::" record, which already exists. Audio or video embedded inside a document is NOT extracted, so never look for or promise a "__MEDIA__" record for it.
 - 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 the table "book_chapters" - never collapse the whole book into a single record. INDEX each chapter record on its chapter number (so chapters sort and range-query in order) and include the chapter title among its tags; the 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 put the book-level facts (title, author, language, overall summary, chapter list / table of contents, genre/subjects) onto the "src::" file record that ALREADY EXISTS in "file_summaries", using updateRecords. Do NOT post a second book-level record, and set every chapter record's reference to exactly "src::" + the storage path. This per-chapter completeness OVERRIDES brevity; human-readable summaries only, never raw/binary bytes.
+- EMAIL (.eml, provided inline with "=== EMAIL ===" / "=== BODY ===" / "=== ATTACHMENT i/N: ..." / "=== FORWARDED MESSAGE k (depth d) ===" headings, which always start at column 0; a body line that merely looks like one is body text): you MUST save ONE record per email MESSAGE in the table "email_messages", and a forwarded message inside it (its own "=== EMAIL ===" block) gets its OWN record. Each record carries subject, from, to, cc, date (the Date line: an ISO string when the layer could parse it, otherwise the raw header text), message_id, in_reply_to, and the body text (quoted earlier replies included). INDEX each record on its date as that string exactly as given, and include the sender address, every recipient address and the subject among its tags. Text under an "=== ATTACHMENT" heading is that attachment's extracted content: datafy it by its own kind (rows into "spreadsheet_rows" for a spreadsheet, one record per section for a document), tag those records with the attachment's filename, and give EVERY record the same "src::" reference as the email. Picture attachments are extracted into "__MEDIA__" like any other embedded picture (their media anchor is quoted on the "[picture ...]" line); other attachments are read inline: their content becomes the records above, but no separate FILE or file record exists for one, so never cite a path for it.
 - URL SOURCES: when the source being indexed is a URL rather than an uploaded file (a temporary or signed URL that merely DELIVERS an uploaded file's bytes is not a URL source; that file keeps its storage-path identity), its identity is "src::" + the FULL URL INCLUDING the query string (the query string often selects the content, so dropping it collapses different pages into one identity). If no record with that unique_id exists, create it; if the slot is already taken, update that record or reference it - never mint a variant id. For a WEB PAGE: extract everything on it, infer the page's primary entity type when it is not obvious (product, listing, article, profile), TAG that entity type plus the entities on the page, and INDEX the ONE number every entity of that type can be compared by (a price for a product, a date for an article). Any OTHER URL (a file behind a link) is downloaded and indexed under whichever per-type rule above matches its content. When the URL's content offers more index points than one record carries, add reference-linked records reachable from its "src::" record.
 - This is a background indexing task: do ALL the MCP saving FIRST, never reply mid-task, and never ask the user questions. 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 encoded file bytes in ANY field: no base64, no data: URIs, no hex or blob dumps. A long opaque non-human-readable string is not data - replace it with a structured description of what it encodes. If base64 or a data: URI is all you have for something, describe it conceptually and never paste it; if nothing human-readable can be extracted at all, OMIT that record rather than saving noise.
 - COMPLETION SIGNAL: only when YOU paged the file yourself with readFileContent and it reported "END OF FILE", with every row/item saved, end your final message with the token INDEXING_COMPLETE on its own line. If more rows remain, do NOT write that token - leaving it out is how the system knows to run another pass to continue. When the file arrives INSIDE this message one window at a time (an embedded window of rows/text, or rendered PDF page images), you are NOT the one who decides it is finished: the system advances the window off the real page/row count and sends the next pass automatically, so save this window, report what you saved, and never imply you have seen the whole file.

package/src/engine/prompts/indexing_user_message.ts

@@ -36,9 +36,11 @@ export type IndexingAttachmentInfo = {
 
 export type BuildIndexingUserMessageOptions = {
 	/**
-	 * For files with no paged reader (.epub/.hwp/.doc/.rtf, source code) the model can't read the binary via
-	 * web_fetch, so the proxy worker extracts the text server-side and replaces
-	 * this exact token with it. When provided, the message embeds the token (and
+	 * For files the layer parses server-side (office, e-book, email) and for text
+	 * files, the text is inlined server-side: a binary container cannot be read via
+	 * web_fetch, and a text file is inlined so providers without a file-fetch tool
+	 * still see it. The proxy worker extracts the text and replaces this exact
+	 * token with it. When provided, the message embeds the token (and
 	 * drops the temporary-URL line - there is nothing for the model to fetch).
 	 */
 	inlineContentPlaceholder?: string;
@@ -65,6 +67,28 @@ export function indexingAccessGroup(attachment: { accessGroup?: string }): 'publ
 	return g === 'public' || g === 'private' ? g : 'authorized';
 }
 
+/**
+ * The folders a file was uploaded into, as a readable trail.
+ *
+ * WHY IT IS ITS OWN LINE and not left implicit in the storage path: people file things
+ * meaningfully. "2026/Q2/royalties/settlement.xlsx" says what the numbers ARE in a way no
+ * amount of reading the grid recovers, and a sheet of bare figures under
+ * "inspections/KCG-B507/" is about one aircraft. The path is already in the metadata block,
+ * but as one string it reads as an address to pass to a tool, which is how it has been used.
+ *
+ * Returns '' for a file at the root, so the line simply does not appear rather than showing
+ * an empty value.
+ */
+export function indexingFolderTrail(storagePath: string): string {
+	if (typeof storagePath !== 'string' || !storagePath) return '';
+	const parts = storagePath.split('/').filter(Boolean);
+	// The last segment is the file itself, and a folder named only by a date or an id tells
+	// the reader nothing this line is for, so it is kept rather than filtered: deciding which
+	// folder names are meaningful is the model's job, not this function's.
+	parts.pop();
+	return parts.join(' / ');
+}
+
 export function buildIndexingUserMessage(
 	attachment: IndexingAttachmentInfo,
 	options?: BuildIndexingUserMessageOptions,
@@ -74,6 +98,10 @@ export function buildIndexingUserMessage(
 		`File metadata:\n` +
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${attachment.storagePath}\n` +
+		// Context, not an address. See indexingFolderTrail.
+		(indexingFolderTrail(attachment.storagePath)
+			? `- folders it was filed under: ${indexingFolderTrail(attachment.storagePath)}\n`
+			: '') +
 		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
 		(typeof attachment.size === 'number' ? `- size (bytes): ${attachment.size}\n` : '') +
 		// Stated in the metadata block as well as the system prompt because this is
@@ -194,6 +222,10 @@ function buildRenderMeta(attachment: IndexingAttachmentInfo): string {
 		`File metadata:\n` +
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${attachment.storagePath}\n` +
+		// Context, not an address. See indexingFolderTrail.
+		(indexingFolderTrail(attachment.storagePath)
+			? `- folders it was filed under: ${indexingFolderTrail(attachment.storagePath)}\n`
+			: '') +
 		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
 		`- access group (use this for EVERY record you write for this file): ${indexingAccessGroup(attachment)}\n`
 	);
@@ -287,6 +319,10 @@ export function buildIndexingContinueMessage(attachment: IndexingAttachmentInfo)
 		`File metadata:\n` +
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${attachment.storagePath}\n` +
+		// Context, not an address. See indexingFolderTrail.
+		(indexingFolderTrail(attachment.storagePath)
+			? `- folders it was filed under: ${indexingFolderTrail(attachment.storagePath)}\n`
+			: '') +
 		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
 		`- access group (use this for EVERY record you write for this file): ${indexingAccessGroup(attachment)}\n` +
 		`\nRecords for the earlier windows/pages of this file are ALREADY saved (they reference "${src}"). ` +

package/src/engine/requests.ts

@@ -12,10 +12,10 @@
  */
 import { buildIndexingSystemPrompt, buildIndexingUserMessage, buildIndexingContinueMessage, buildIndexingRenderMessage, buildIndexingRenderContinueTemplate, buildIndexingWindowMessage } from './prompts';
 import { isServerExtractable, isPagedReadFile, isImageVisionFile, isWindowedReadFile, makeExtractPlaceholder, makeRenderPlaceholder, makeWindowPlaceholder, RENDER_PAGES_PER_WINDOW, type ExtractDirective, type FileUrlDirective } from './office';
-import { chatEngineConfig, pollOpt, windowedIndexingEnabled } from './config';
+import { chatEngineConfig, pollOpt, windowedIndexingEnabled, liveStreamingEnabled, liveStreamingRealtimeEnabled } from './config';
 // Output sizing lives in budget.ts so the request cap and the reserve the input
 // budget subtracts cannot drift; getMaxOutputTokens also clamps per model.
-import { getMaxOutputTokens } from './budget';
+import { getMaxOutputTokens, getModelContextWindow } from './budget';
 
 export const ANTHROPIC_MESSAGES_API_URL = 'https://api.anthropic.com/v1/messages';
 const ANTHROPIC_MODELS_API_URL = 'https://api.anthropic.com/v1/models';
@@ -39,6 +39,70 @@ export const DEFAULT_OPENAI_MODEL = 'gpt-5.6-luna';
 
 const mcpUrl = () => chatEngineConfig().mcpBaseUrl;
 
+/**
+ * The MCP endpoint an INDEXING pass points at.
+ *
+ * Same server, same auth, same tools it can actually call: `?profile=index` only narrows
+ * the tools/list the model is SHOWN. An indexing pass reads one window of one file and
+ * writes records for it, so being told about deleteRecords, exportRecordsToFile,
+ * writeReport, getTemporaryUrl, getProfile and getProjectInfos costs about 2,400 tokens
+ * on every pass of every file and buys nothing: there is no user attached to hand a
+ * download or a report to, and re-index clears old records server-side before the pass
+ * runs. Measured: 30,577 B -> 20,755 B.
+ *
+ * A CHAT turn keeps the full list and always will. It is open ended, a person can ask
+ * for anything, and a tool that is missing from the list is a dead end the model cannot
+ * reason its way out of.
+ *
+ * Degrades in both directions, which is why it is a query param: an MCP server that
+ * predates it ignores the parameter and serves the full list, and a client that predates
+ * it just sends no parameter. Neither needs the other deployed first.
+ */
+/**
+ * Append query parameters to an MCP endpoint, preserving any the base already carries.
+ *
+ * An explicit path before the query. The configured base has no trailing slash
+ * ("https://mcp-dev.broadwayinc.computer"), and appending "?profile=index" straight onto an
+ * authority with no path yields a URL that is legal but that intermediaries and clients
+ * normalise inconsistently. "/?profile=index" is unambiguous everywhere.
+ *
+ * Every parameter here is a HINT the server may ignore, which is what lets the two sides
+ * deploy in either order: a server that predates one ignores it, and a client that predates
+ * it sends nothing. The worker strips the whole query before appending its own /internal
+ * paths (_mcp_endpoint_and_token), so nothing added here reaches those routes.
+ */
+function withMcpParams(base: string, params: Record<string, string | number | undefined>): string {
+	if (!base) return base;
+	const pairs = Object.keys(params)
+		.filter(k => params[k] !== undefined && params[k] !== null && params[k] !== '')
+		.map(k => encodeURIComponent(k) + '=' + encodeURIComponent(String(params[k])));
+	if (!pairs.length) return base;
+	const [addr, existing] = base.split('?');
+	// Only supply the missing root path. Appending a slash to a base that ALREADY has a
+	// path would change where the request lands on a server mounted under one.
+	const hasPath = /^[a-z][a-z0-9+.-]*:\/\/[^/]+\/./i.test(addr);
+	const path = hasPath ? addr : addr.replace(/\/+$/, '') + '/';
+	return path + '?' + (existing ? existing + '&' : '') + pairs.join('&');
+}
+
+/**
+ * How large a page of a paginated tool result this model can afford.
+ *
+ * The server slices big results into pages and the model spends one round trip per page, so
+ * the page size sets how long reading a large record set takes: 1000 spreadsheet records is
+ * 74 round trips at the server's floor of 10,000 chars and 13 at 60,000. The server cannot
+ * know which model is on the other end of an MCP connection, so it is told.
+ *
+ * The MODEL's own ceiling, not getContextWindow(): the project's context-window setting
+ * budgets this client's FIRST request, while these pages accumulate in the provider's
+ * server-side tool loop, which runs against what the model can actually hold.
+ */
+const mcpContextParam = (platform: 'claude' | 'openai', model?: string) =>
+	getModelContextWindow(platform, model);
+
+const mcpIndexingUrl = (platform: 'claude' | 'openai' = 'openai', model?: string) =>
+	withMcpParams(mcpUrl(), { profile: 'index', ctx: mcpContextParam(platform, model) });
+
 /**
  * Where a chat turn's MCP tools point, and what they authenticate with.
  *
@@ -72,6 +136,85 @@ function mcpEndpointFor(
 }
 const clientSecretRequest = (opts: any) => chatEngineConfig().clientSecretRequest(opts);
 
+/**
+ * THE two `stream` flags of a streamed chat turn, produced together or not at all.
+ *
+ * There are two of them and they are NOT the same flag:
+ *
+ *   * `transport.stream` is SKAPI's. It tells the polling worker to read the
+ *     destination's response incrementally and append the raw bytes to the chunk
+ *     table, and it is never sent on to the destination.
+ *   * `body.stream` is the DESTINATION's own field, and BunnyQuery is the party
+ *     that may set it: skapi relays bytes and knows no vendor, so it cannot know
+ *     that Anthropic Messages and OpenAI Responses both happen to spell it
+ *     `stream` at the top level of the body.
+ *
+ * Setting one without the other fails QUIETLY, which is why they are produced by
+ * one function from one boolean and returned as one object:
+ *
+ *   * body streams, skapi buffers -> the row stores an SSE TRANSCRIPT where
+ *     extractClaudeText / extractOpenAIText expect a parsed document, so the turn
+ *     reads back as an empty answer with nothing in the logs to say why.
+ *   * skapi streams, the body never asked -> the destination sends one plain
+ *     document, the relay chops it into chunks, the frame parser finds no framing
+ *     at all, and the row settles with a status and no body.
+ *
+ * Two frozen constants rather than a fresh object per call: the pair is a
+ * CONSTANT, and an object literal built at each call site is exactly the shape
+ * that drifts when someone edits one arm.
+ */
+export type ChatStreamWiring = {
+	/** Spread into the clientSecretRequest OPTIONS (skapi's relay switch). `realtime`
+	 *  belongs here and never in `body`: it is skapi's, not the destination's. */
+	transport: { stream?: true; realtime?: true };
+	/** Spread into `data` (the destination's own switch). */
+	body: { stream?: true };
+};
+const CHAT_STREAM_ON: ChatStreamWiring = Object.freeze({
+	transport: Object.freeze({ stream: true as true }),
+	body: Object.freeze({ stream: true as true }),
+}) as ChatStreamWiring;
+const CHAT_STREAM_OFF: ChatStreamWiring = Object.freeze({
+	transport: Object.freeze({}),
+	body: Object.freeze({}),
+}) as ChatStreamWiring;
+
+/**
+ * Both stream flags for a CHAT turn, from the one `liveStreaming` opt-in.
+ *
+ * Chat turns only. Deliberately NOT called from:
+ *   * the model LISTING calls (listClaudeModels / listOpenAIModels) - plain GETs
+ *     with no body at all, and a listing has nothing to stream;
+ *   * notifyAgentSaveAttachment (background INDEXING) - see the note there.
+ *
+ * `queue` is asked for because a chat turn sent WITH ATTACHMENTS runs on the
+ * background queue ("<userId>-bg") so it waits behind its own files, and that one
+ * must not stream either. Not for the indexing reasons above: the reason is
+ * RECOVERY. A streamed row keeps no body, so its only recovery after a reload is a
+ * poll re-attached with a reader, and the re-attach loop classifies everything on
+ * the bg queue as a background poll (flat cadence, no reader, that is what the
+ * MAX_CONCURRENT_BG_POLLS budget is for). Such a turn would therefore settle on an
+ * empty envelope and the answer would be gone. Losing the live rendering on the
+ * one kind of turn that already waited minutes for its files is the cheaper half of
+ * that trade.
+ */
+const CHAT_STREAM_ON_REALTIME: ChatStreamWiring = Object.freeze({
+	// `realtime` rides on the TRANSPORT arm only. It is a skapi option, not a field
+	// the destination understands, so it must never reach `data`: the body arm stays
+	// exactly what it is with the socket off.
+	transport: Object.freeze({ stream: true as true, realtime: true as true }),
+	body: Object.freeze({ stream: true as true }),
+}) as ChatStreamWiring;
+
+export function chatStreamWiring(queue?: string): ChatStreamWiring {
+	if (!liveStreamingEnabled()) return CHAT_STREAM_OFF;
+	if (isBgIndexingQueue(queue)) return CHAT_STREAM_OFF;
+	// Socket delivery is a separate opt-in from streaming itself: see
+	// liveStreamingRealtime for why a host that does not own its skapi instance
+	// should leave it off.
+	return liveStreamingRealtimeEnabled() ? CHAT_STREAM_ON_REALTIME : CHAT_STREAM_ON;
+}
+
 // Resolve the per-image `detail` for OpenAI. The version match tolerates a
 // trailing variant/date suffix (`gpt-5.4-nano`, `-mini`, `-2026-01-01`, …):
 // previously the pattern was anchored with no suffix allowed, so EVERY suffixed
@@ -455,6 +598,17 @@ export type CallClaudeWithMcpParams = {
 // engine's own poll sites and imported by agent.vue; the widget carries its own
 // copy in src/index.js that must be kept in step.
 export const POLL_INTERVAL = 3000;
+// Poll cadence while a turn is STREAMING, i.e. while the poll is also reading the
+// relayed chunks. Faster than POLL_INTERVAL because on a streaming poll the tick is
+// not just "is it done yet", it is the delivery of the answer: at 3s the reader
+// watches the text arrive in three-second steps.
+//
+// 1s and not less, because the relay coalesces its writes to about one per second
+// (the worker's byte budget, see the polling worker's _STREAM_FLUSH_INTERVAL_S), so
+// a faster poll reads the same rows again and buys nothing but requests. It is also
+// what makes "roughly one paint per second" fall out of the transport rather than
+// out of a timer the paint path has to guess at.
+export const STREAM_POLL_INTERVAL = 1000;
 // Ceiling on how many BACKGROUND indexing polls may be attached at once, across
 // every poll site (the engine's drain, the engine's history load, and each
 // client's own fallback poller).
@@ -500,12 +654,20 @@ export async function callClaudeWithMcp({
 		mcpServerDefinition.authorization_token = mcpServer.authorizationToken;
 	}
 
+	// ONE decision, spread in TWO places. See chatStreamWiring: the transport half
+	// is skapi's relay switch and the body half is Anthropic's own, and a turn that
+	// carries one without the other fails silently rather than loudly. The queue is
+	// the same expression the request uses below, so an attachment turn (which runs
+	// on the bg queue) is recognised and left buffered.
+	const stream = chatStreamWiring(userId || service);
+
 	return clientSecretRequest({
 		clientSecretName: 'claude',
 		queue: userId || service,
 		service,
 		owner,
 		...pollOpt(),
+		...stream.transport,
 		url: ANTHROPIC_MESSAGES_API_URL,
 		method: 'POST',
 		headers: {
@@ -517,6 +679,9 @@ export async function callClaudeWithMcp({
 		data: {
 			model,
 			max_tokens: maxTokens,
+			// Top level beside model/messages/mcp_servers, which is where the
+			// Messages API takes it.
+			...stream.body,
 			...(extractContent && extractContent.length
 				? { _skapi_extract: extractContent }
 				: {}),
@@ -596,7 +761,9 @@ export async function callClaudeWithPublicMcp(
 		fileUrls,
 		mcpServer: {
 			name: MCP_NAME,
-			url: endpoint.url,
+			url: withMcpParams(endpoint.url, {
+				ctx: mcpContextParam('claude', model || DEFAULT_CLAUDE_MODEL),
+			}),
 			// Omitted entirely for an anonymous turn; the `if (mcpServer.authorizationToken)`
 			// guard below drops the key rather than sending an empty one.
 			authorizationToken: endpoint.token,
@@ -648,12 +815,16 @@ export async function callOpenAIWithPublicMcp(
 		})),
 	];
 
+	// ONE decision, spread in TWO places - see chatStreamWiring.
+	const stream = chatStreamWiring(userId || service);
+
 	return clientSecretRequest({
 		clientSecretName: 'openai',
 		queue: userId || service,
 		service,
 		owner,
 		...pollOpt(),
+		...stream.transport,
 		url: OPENAI_RESPONSES_API_URL,
 		method: 'POST',
 		headers: {
@@ -663,6 +834,9 @@ export async function callOpenAIWithPublicMcp(
 		data: {
 			model: resolvedModel,
 			max_output_tokens: getMaxOutputTokens('openai', resolvedModel),
+			// Top level beside model/input/tools, which is where the Responses API
+			// takes it.
+			...stream.body,
 			...(extractContent && extractContent.length
 				? { _skapi_extract: extractContent }
 				: {}),
@@ -674,7 +848,7 @@ export async function callOpenAIWithPublicMcp(
 				{
 					type: 'mcp',
 					server_label: MCP_NAME,
-					server_url: endpoint.url,
+					server_url: withMcpParams(endpoint.url, { ctx: mcpContextParam('openai', resolvedModel) }),
 					require_approval: 'never',
 					// No `headers` at all for an anonymous turn: `Bearer ` with an
 					// empty token is a credential the MCP server rejects, and the
@@ -945,6 +1119,22 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 		accessGroup: attachment.accessGroup,
 	});
 
+	// INDEXING NEVER STREAMS, on either platform, whatever `liveStreaming` says.
+	// chatStreamWiring is deliberately not called below, and neither `stream` flag
+	// appears in either branch. Three reasons, any one of which is sufficient:
+	//
+	//   1. Nobody is watching. A pass runs on the background queue behind a chain
+	//      that can span days; there is no bubble to paint it into, so the only
+	//      thing streaming would buy is a chunk table to clean up.
+	//   2. The worker has to READ this response. `auto_continue` (render and window
+	//      passes) decides whether to enqueue the next window from the reply, and
+	//      the truncation and auth-outage checks that stop a chain read it too.
+	//      Those need a real JSON body, and a streamed row settles with a status and
+	//      no body at all.
+	//   3. The worker degrades such a pass anyway (it clears `strm` before the call
+	//      fires), so asking would be a request the backend is guaranteed to refuse
+	//      to honour - and one that leaves the row briefly marked as streaming,
+	//      which is exactly the state csr-finalize gates on.
 	if (platform === 'openai') {
 		const resolvedModel = info.model || DEFAULT_OPENAI_MODEL;
 		const imageDetail = getOpenAIImageDetail(resolvedModel);
@@ -962,7 +1152,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 			},
 			data: {
 				model: resolvedModel,
-				max_output_tokens: getMaxOutputTokens('openai', resolvedModel),
+				max_output_tokens: getMaxOutputTokens('openai', resolvedModel, 'indexing'),
 				// Nano-only transcription knobs. Indexing only; see variantIndexingOptions.
 				...variantIndexingOptions(resolvedModel),
 				...skapiExtract,
@@ -980,7 +1170,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 					{
 						type: 'mcp',
 						server_label: MCP_NAME,
-						server_url: mcpUrl(),
+						server_url: mcpIndexingUrl('openai', resolvedModel),
 						require_approval: 'never',
 						headers: { Authorization: 'Bearer $ACCESS_TOKEN' },
 					},
@@ -1014,7 +1204,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 		},
 		data: {
 			model: resolvedModel,
-			max_tokens: getMaxOutputTokens('claude', resolvedModel),
+			max_tokens: getMaxOutputTokens('claude', resolvedModel, 'indexing'),
 			...skapiExtract,
 			...skapiRender,
 			...skapiWindow,
@@ -1036,7 +1226,7 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 				{
 					type: 'url',
 					name: MCP_NAME,
-					url: mcpUrl(),
+					url: mcpIndexingUrl('claude', resolvedModel),
 					authorization_token: '$ACCESS_TOKEN',
 				},
 			],
@@ -1112,6 +1302,11 @@ export function extractOpenAIText(response: any) {
 	return '';
 }
 
+// MODEL LISTINGS NEVER STREAM. Both are plain GETs with no body: there is no
+// destination-side `stream` field to pair skapi's with, and a listing is one small
+// document that a caller reads whole. Neither carries `poll` either, so there is
+// not even a reader to hand chunks to. chatStreamWiring is deliberately not called
+// here - the pair is chat-turn-only.
 export async function listClaudeModels(service: string, owner: string) {
 	return clientSecretRequest({
 		clientSecretName: 'claude',