bunnyquery 1.9.0 → 1.9.4

package/package.json

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

package/src/engine/host.ts

@@ -20,6 +20,19 @@ export interface ChatIdentity {
 	owner: string;
 	/** Per-user queue name (falls back to projectId). */
 	userId: string;
+	/**
+	 * This chat is being used by a visitor with NO account, on a project whose
+	 * owner allows that.
+	 *
+	 * It changes where the MCP tools point. A signed-in turn goes to the MCP
+	 * server's root endpoint and authenticates with the caller's own token; an
+	 * anonymous turn has no token to send, and an EMPTY one is worse than none
+	 * (the server cannot identify a project from it, and an empty credential may
+	 * be rejected by the provider before the request is even made). So an
+	 * anonymous turn goes to the project-scoped endpoint instead, which is
+	 * read-only, restricted to public records, and needs no credential at all.
+	 */
+	anonymous?: boolean;
 	platform: 'claude' | 'openai' | 'none';
 	model?: string;
 	serviceName?: string;
@@ -250,6 +263,22 @@ export interface ChatHost {
 	 * whichever pass got there first created the record and the others hoped it had.
 	 */
 	ensureFileIndexRecord?(storagePath: string, meta?: { name?: string; mime?: string; size?: number }): Promise<any>;
+	/**
+	 * The access group this file's records must be written at: the uploader's
+	 * choice, which is the project default or a per-upload answer.
+	 *
+	 * Asked PER FILE, and asked AFTER ensureFileIndexRecord has run, because the
+	 * host is what actually creates the "src::" record and it must report the
+	 * group it really used. The engine threads the answer into the indexing
+	 * prompts so the agent's own records land in the same group; a record saved
+	 * under a different group is in a different table and never comes back with
+	 * the rest of the file.
+	 *
+	 * Optional and may return a promise. A host without it (or one that returns
+	 * nothing) gets "authorized", which is what every record used before the
+	 * setting existed.
+	 */
+	uploadAccessGroup?(storagePath: string): 'public' | 'authorized' | 'private' | undefined | Promise<'public' | 'authorized' | 'private' | undefined>;
 	/** Map a relative path to the consumer's db storage key (e.g. uid-prefixed). */
 	storagePathFor(relPath: string): string;
 	getMimeType(name: string): string | null;

package/src/engine/indexing_groups.ts

@@ -289,6 +289,23 @@ export type RunStubInfo = {
 	platform?: 'claude' | 'openai';
 };
 
+/** Canonical form of an indexing key for COMPARISON only (never for storage).
+ *
+ *  The two sides of every stub-vs-group comparison come from one string but by two
+ *  routes: the run:: record id keeps `attachment.storagePath` verbatim
+ *  (requests.ts runIndexUniqueId), while the group's key is recovered from the pass
+ *  prompt and trimmed on the way (history.ts parseIndexingRequestText). A path whose
+ *  first or last character is whitespace therefore produced two keys for one file, the
+ *  stub was never suppressed, and the file drew two rows.
+ *
+ *  Trim only. NOT NFC: both keys derive from the same string with no normalization on
+ *  either side, so no NFC/NFD divergence is reachable here, and normalizing a key that
+ *  is also an S3 object key elsewhere is how storage paths get silently renamed.
+ */
+export function canonIndexKey(s?: string): string {
+	return typeof s === 'string' && s ? s.trim() : '';
+}
+
 /** A 'working' run record older than this with no live-queue confirmation is
  *  treated as unknown rather than live: a chain that died without reaching any
  *  error path leaves 'working' dangling, and a row must not spin forever on a
@@ -413,6 +430,10 @@ export function buildChatDisplayList(
 	var openRunOfKey: { [key: string]: string } = {};
 	var runsOfKey: { [key: string]: string[] } = {};
 	var keyOfRun: { [runId: string]: string } = {};
+	// Newest pass timestamp seen for each open run, so a FIRST pass can be told from a
+	// re-index (it arrives AFTER the run it follows) apart from a misordered older pass
+	// (it arrives before). Only the second must not re-open.
+	var newestTsOfRun: { [runId: string]: number } = {};
 	var runSeq = 0;
 
 	for (var i = 0; i < list.length; i++) {
@@ -421,7 +442,18 @@ export function buildChatDisplayList(
 
 		var runId: string | undefined;
 		var ref = msg.role === 'user' ? readFileRef(msg) : null;
-		if (ref) {
+		// A pass already attributed to a run stays with it, whatever its label says.
+		// Reading the label FIRST made attribution depend on walk order: a first pass
+		// ("A new file has just been uploaded") re-opened its file's run at the line
+		// below, so if history delivered a run's continuations before its first pass -
+		// which paging and the bg merge can do - the continuations opened a run, the
+		// late first pass deleted it and opened a second, and the abandoned one was
+		// force-finished. One run then rendered as TWO rows for the same file: a green
+		// "complete" and a yellow "in progress". The same applies to a duplicate copy
+		// of a pass. The id is the stable identity here; the label is a description.
+		if (msg._serverItemId && runByItemId[msg._serverItemId]) {
+			runId = runByItemId[msg._serverItemId];
+		} else if (ref) {
 			// Path first — a file can be re-uploaded under a name that already
 			// exists elsewhere. But a pass that supplied no path (a compact
 			// continuation label recovered from an old history cache) is still the
@@ -431,7 +463,24 @@ export function buildChatDisplayList(
 			// A FIRST pass ("A new file has just been uploaded") when this file
 			// already has a run open starts a new one: it is a re-index, or a
 			// re-upload over the same storage path. Continuations join the run.
-			if (!ref.continued && openRunOfKey[key]) delete openRunOfKey[key];
+			//
+			// ...but only when this pass is genuinely NEW. A first pass whose id is
+			// already attributed is the same pass reached twice (a duplicate bubble, or
+			// a walk that reaches it after the continuations it opened), and re-opening
+			// on it splits one run in half.
+			var alreadySeen = !!(msg._serverItemId && runByItemId[msg._serverItemId]);
+			// ...and only when it is actually LATER than the run it would replace. A
+			// re-index's first pass follows the previous run; a misordered one precedes
+			// the continuations already walked, and re-opening on it abandons a live run
+			// (rendered green "complete") beside the fragment (yellow "in progress").
+			// Timestamps decide it when both are known; without them the old
+			// label-only behaviour stands, so the re-index case is unchanged.
+			var openId = openRunOfKey[key];
+			var notLater = false;
+			if (openId && typeof msg._ts === 'number' && typeof newestTsOfRun[openId] === 'number') {
+				notLater = (msg._ts as number) <= newestTsOfRun[openId];
+			}
+			if (!ref.continued && !alreadySeen && !notLater && openRunOfKey[key]) delete openRunOfKey[key];
 			runId = openRunOfKey[key];
 			if (!runId) {
 				runId = 'run' + (runSeq++);
@@ -439,8 +488,6 @@ export function buildChatDisplayList(
 				keyOfRun[runId] = key;
 				(runsOfKey[key] || (runsOfKey[key] = [])).push(runId);
 			}
-		} else if (msg._serverItemId && runByItemId[msg._serverItemId]) {
-			runId = runByItemId[msg._serverItemId];
 		} else if (msg.role !== 'user') {
 			// ADJACENT only. Both paths that create a pass emit its request and
 			// response bubbles together, so an id-less response belongs to the
@@ -455,6 +502,10 @@ export function buildChatDisplayList(
 		// or a response whose request is not loaded) stays an ordinary message
 		// rather than being folded into whichever group happens to be nearest.
 		if (!runId) continue;
+		if (typeof msg._ts === 'number') {
+			var prevTs = newestTsOfRun[runId];
+			if (typeof prevTs !== 'number' || (msg._ts as number) > prevTs) newestTsOfRun[runId] = msg._ts as number;
+		}
 
 		var g = groups[runId];
 		if (!g) {
@@ -780,16 +831,18 @@ export function buildChatDisplayList(
 		var coveredPathlessNames: { [k: string]: boolean } = {};
 		for (var ci = 0; ci < order.length; ci++) {
 			var cg = groups[order[ci]];
-			if (cg.path) { coveredPaths[cg.path] = true; if (cg.key) coveredPaths[cg.key] = true; }
-			else if (cg.name) coveredPathlessNames[cg.name] = true;
-			else if (cg.key) coveredPaths[cg.key] = true;
+			if (cg.path) {
+				coveredPaths[canonIndexKey(cg.path)] = true;
+				if (cg.key) coveredPaths[canonIndexKey(cg.key)] = true;
+			} else if (cg.name) coveredPathlessNames[canonIndexKey(cg.name)] = true;
+			else if (cg.key) coveredPaths[canonIndexKey(cg.key)] = true;
 		}
 		var now = opts && typeof opts.now === 'number' ? opts.now : Date.now();
 		var stubClearedAt = (opts && typeof opts.stubClearedAt === 'number' && opts.stubClearedAt > 0)
 			? opts.stubClearedAt : 0;
 		for (var sp in runStubs) {
 			var rec = runStubs[sp];
-			if (!sp || !rec || !rec.status || coveredPaths[sp]) continue;
+			if (!sp || !rec || !rec.status || coveredPaths[canonIndexKey(sp)]) continue;
 			var fname = rec.filename || sp.split('/').pop() || sp;
 			// A PATHLESS group (legacy compact label) can only be matched by
 			// name, and that is still the right match: the file already has a
@@ -797,7 +850,7 @@ export function buildChatDisplayList(
 			// void. What is gone is the reverse — a group WITH a path no longer
 			// writes into the name namespace, so it can no longer delete a
 			// same-basename stub from another folder.
-			if (coveredPathlessNames[fname]) continue;
+			if (coveredPathlessNames[canonIndexKey(fname)]) continue;
 			// A run recorded under the OTHER platform's chat belongs to that
 			// conversation: its passes live in that history (so no real group
 			// can ever cover this stub) and the queue probe is platform-scoped
@@ -808,7 +861,26 @@ export function buildChatDisplayList(
 			// whatever the record says (a lagged update must not paint a verdict over
 			// visible work), then the record's own terminal statuses, then the
 			// queue's authoritative ABSENCE, and only then the stated wait.
-			var live = !!liveIndexKeys[sp] || !!liveIndexKeys[fname];
+			// The bare-NAME disjunct is load-bearing: a legacy pass prompt may carry no
+			// storage path at all, so the name is the only key its run can appear under.
+			// But it also matched ANY live file sharing this basename, painting a
+			// finished run's stub yellow because a same-named file in another folder was
+			// indexing. Take the name hit only when it cannot belong to a different
+			// file - i.e. no OTHER live key is a path ending in this basename.
+			var live = !!liveIndexKeys[sp] || !!liveIndexKeys[canonIndexKey(sp)];
+			if (!live && (liveIndexKeys[fname] || liveIndexKeys[canonIndexKey(fname)])) {
+				var claimedByOther = false;
+				for (var lk in liveIndexKeys) {
+					if (!liveIndexKeys[lk]) continue;
+					var lkc = canonIndexKey(lk);
+					if (lkc === canonIndexKey(sp)) continue;
+					if (lkc.length > fname.length && lkc.slice(-(fname.length + 1)) === '/' + fname) {
+						claimedByOther = true;
+						break;
+					}
+				}
+				live = !claimedByOther;
+			}
 			// Cleared-history horizon: a run that ended at or before the clear is
 			// part of what the user asked to forget. A live queue hit survives it
 			// (see BuildDisplayListOptions.stubClearedAt). A record carrying NO
@@ -825,7 +897,8 @@ export function buildChatDisplayList(
 				// A done:: marker from the same sweep is as terminal as the record's
 				// own 'done' — it settles a dangling 'working' the chain never
 				// flipped (mirrors the real-group doneKeys disjunct).
-				if (rec.status === 'done' || doneKeys[sp] || doneKeys[fname]) { st = 'done'; fin = true; }
+				if (rec.status === 'done' || doneKeys[sp] || doneKeys[canonIndexKey(sp)]
+					|| doneKeys[fname] || doneKeys[canonIndexKey(fname)]) { st = 'done'; fin = true; }
 				else if (rec.status === 'error') { st = 'error'; fin = true; }
 				else if (rec.status === 'cancelled') { st = 'cancelled'; fin = true; }
 				else if (liveIndexChecked) {
@@ -903,11 +976,14 @@ export function buildChatDisplayList(
 	// the first pass paged in, and again when paging ended. A record with a
 	// `started` places the run at ONE spot for as long as the record exists.
 	var suppressAnchor: { [runId: string]: boolean } = {};
+	var stubByCanon: { [k: string]: RunStubInfo } = {};
+	if (runStubs) for (var ck in runStubs) stubByCanon[canonIndexKey(ck)] = runStubs[ck];
 	if (runStubs) {
 		for (var ti2 = 0; ti2 < order.length; ti2++) {
 			var tg = groups[order[ti2]];
 			if (!newestRunOfKey[order[ti2]]) continue;
-			var trec = (tg.path && runStubs[tg.path]) || runStubs[tg.key];
+			var trec = (tg.path && (runStubs[tg.path] || stubByCanon[canonIndexKey(tg.path)]))
+				|| runStubs[tg.key] || stubByCanon[canonIndexKey(tg.key)];
 			if (!trec || typeof trec.started !== 'number') continue;
 			if (stubPlatform && trec.platform && trec.platform !== stubPlatform) continue;
 			suppressAnchor[order[ti2]] = true;

package/src/engine/prompts/chat_system_prompt.ts

@@ -36,16 +36,35 @@ export type ChatSystemPromptParams = {
 	 * given when the caller says which one this is.
 	 */
 	client?: 'console' | 'widget';
+	/**
+	 * The access group THIS project's indexer writes its records at, from the
+	 * project's `default_access_group` setting.
+	 *
+	 * 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
+	 * hardcoded to it. Now a project can index at "public" (so an anonymous
+	 * 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.
+	 */
+	indexAccessGroup?: string;
 };
 
 export function buildChatSystemPrompt(params: ChatSystemPromptParams): string {
 	const { projectId, serviceName, serviceDescription, greeting, canUpload, client } = params;
+	// Rendered as the model would have to WRITE it in a tool call: the named
+	// aliases go in quotes, a raw group number does not.
+	const g = params.indexAccessGroup;
+	const indexGroupLiteral =
+		typeof g === 'number' ? String(g)
+		: (g === 'public' || g === 'private' || g === 'authorized' || g === 'admin') ? `"${g}"`
+		: '"authorized"';
 
 	let systemPrompt = `
 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" (where the indexer writes; pass access_group explicitly, including 0, to search another group), 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.
+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.
 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.

package/src/engine/prompts/index.ts

@@ -9,6 +9,7 @@ export { buildChatSystemPrompt, type ChatSystemPromptParams } from './chat_syste
 export { buildIndexingSystemPrompt, type IndexingSystemPromptParams } from './indexing_system_prompt';
 export {
 	buildIndexingUserMessage,
+	indexingAccessGroup,
 	buildIndexingContinueMessage,
 	buildIndexingRenderMessage,
 	buildIndexingRenderContinueTemplate,

package/src/engine/prompts/indexing_system_prompt.ts

@@ -14,10 +14,21 @@ export type IndexingSystemPromptParams = {
 	serviceName?: string;
 	/** Project description. When present, name + description are appended. */
 	serviceDescription?: string;
+	/**
+	 * Access group every record written during this run must carry. Chosen by the
+	 * uploader (project default, or a per-upload prompt) and already applied to
+	 * the "src::" file record before indexing starts. Defaults to "authorized",
+	 * which is what every record written before this setting existed used.
+	 */
+	accessGroup?: 'public' | 'authorized' | 'private';
 };
 
 export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): string {
 	const { projectId, serviceName, serviceDescription } = params;
+	const accessGroup =
+		params.accessGroup === 'public' || params.accessGroup === 'private'
+			? params.accessGroup
+			: 'authorized';
 
 	let systemPrompt =
 `You are a background indexing agent for project ${projectId}.
@@ -28,7 +39,8 @@ export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): s
 - 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).
 - TRANSCRIBE, DO NOT DESCRIBE. When an image contains ANY text - a label, tag, stamp, form field, serial/part number, handwriting - your FIRST job is to read the characters out and store them VERBATIM, not to describe the scene. A record saying "a red inspection tag with handwritten markings" is worthless: it is unsearchable and every such photo produces the same sentence. Put the characters you can actually read into these EXACT fields, not variations of them: "printed_text" (the pre-printed wording), "handwritten_text" (what a person wrote by hand), and, when you can resolve one, "part_no", "tag_id" and "date". Same reason as the fixed table names: a field called photo_text in one pass and visible_text_notes in the next cannot be queried together. Read PARTIAL values rather than skipping: "500.7402.52__" beats nothing. Only when a character is genuinely unreadable, leave that field null or mark the unreadable span - do NOT invent it, and do NOT replace the whole transcription with a description of what the object looks like. A scene description is a nice extra AFTER the text, never instead of it.
 - IMAGE FILES uploaded as the file itself: if ANY readable character appears ANYWHERE in the image (a label, a stamp, a sign in the background) it counts as an image WITH text - transcribe it per the rule above, and also capture the layout (what appears where) and every entity named. Only a truly text-free image gets description first: a one-line caption, then the objects present with their attributes (type, color, count, condition, position). Either way, save what you extract onto the file's "src::" record with updateRecords, TAG every entity and identifier visible, and INDEX the one number the image offers (a measured value, an amount, a count).
-- 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 "authorized") 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 "authorized") 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.
+- 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.
 - 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.

package/src/engine/prompts/indexing_user_message.ts

@@ -20,6 +20,18 @@ export type IndexingAttachmentInfo = {
 	size?: number;
 	/** Temporary signed URL the agent/MCP fetches to read the file contents. */
 	url: string;
+	/**
+	 * Access group every record extracted from this file must be written at.
+	 *
+	 * The uploader chooses it (project default, or a per-upload prompt), and the
+	 * `src::` file record is already created at this group before indexing starts.
+	 * The rows, chapters and summaries the agent writes have to MATCH it: skapi's
+	 * access group is part of a record's table key, so a public file whose rows
+	 * were saved as "authorized" is a file an anonymous visitor can see the name
+	 * of and none of the contents of. Omitted means "authorized", which is what
+	 * every record written before this setting existed used.
+	 */
+	accessGroup?: 'public' | 'authorized' | 'private';
 };
 
 export type BuildIndexingUserMessageOptions = {
@@ -44,6 +56,15 @@ export type BuildIndexingUserMessageOptions = {
 	pagedRead?: boolean;
 };
 
+/**
+ * The access group to write this file's records at. One place, so the user
+ * message, the continue message and the system prompt cannot disagree.
+ */
+export function indexingAccessGroup(attachment: { accessGroup?: string }): 'public' | 'authorized' | 'private' {
+	const g = attachment && attachment.accessGroup;
+	return g === 'public' || g === 'private' ? g : 'authorized';
+}
+
 export function buildIndexingUserMessage(
 	attachment: IndexingAttachmentInfo,
 	options?: BuildIndexingUserMessageOptions,
@@ -54,7 +75,11 @@ export function buildIndexingUserMessage(
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${attachment.storagePath}\n` +
 		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
-		(typeof attachment.size === 'number' ? `- size (bytes): ${attachment.size}\n` : '');
+		(typeof attachment.size === 'number' ? `- size (bytes): ${attachment.size}\n` : '') +
+		// Stated in the metadata block as well as the system prompt because this is
+		// the per-FILE value: one project can hold public and private files at once,
+		// and the system prompt is what is constant across the run.
+		`- access group (use this for EVERY record you write for this file): ${indexingAccessGroup(attachment)}\n`;
 
 	if (options?.inlineContent) {
 		// Parsed client-side (an attachment-parser plugin). The content is already
@@ -169,7 +194,8 @@ function buildRenderMeta(attachment: IndexingAttachmentInfo): string {
 		`File metadata:\n` +
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${attachment.storagePath}\n` +
-		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '')
+		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
+		`- access group (use this for EVERY record you write for this file): ${indexingAccessGroup(attachment)}\n`
 	);
 }
 
@@ -262,6 +288,7 @@ export function buildIndexingContinueMessage(attachment: IndexingAttachmentInfo)
 		`- name: ${attachment.name}\n` +
 		`- storage path: ${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}"). ` +
 		`First call getRecords with reference "${src}" to see how far the previous pass got (the furthest row/window already saved). The reference ALONE is the whole query: it returns every record written from this file across ALL tables and ALL access groups, so do NOT add table_name or access_group to narrow it. The response is PAGED, so keep fetching pages until it reports there are no more, and take the furthest point from the WHOLE set, never from the first page. ` +
 		`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` +

package/src/engine/requests.ts

@@ -38,6 +38,38 @@ export const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-5';
 export const DEFAULT_OPENAI_MODEL = 'gpt-5.6-luna';
 
 const mcpUrl = () => chatEngineConfig().mcpBaseUrl;
+
+/**
+ * Where a chat turn's MCP tools point, and what they authenticate with.
+ *
+ * A SIGNED-IN turn uses the server's root endpoint with the literal
+ * '$ACCESS_TOKEN', which the backend substitutes from the caller's
+ * `x-access-token` header before the request leaves for the provider.
+ *
+ * An ANONYMOUS turn has no such header, so that substitution yields an EMPTY
+ * credential: `authorization_token: ""` for Claude, `Bearer ` for OpenAI. That is
+ * worse than sending none. The MCP server cannot identify a project from an empty
+ * token, so every tool call 401s — and a pass whose calls all 401 is exactly what
+ * the polling worker classifies as an auth outage, which STOPS the chain. A
+ * provider that validates the field would reject the whole request before that.
+ *
+ * So an anonymous turn points at the project-scoped endpoint `/p/<project id>`
+ * and sends NO credential. That route is anonymous by construction: read-only,
+ * one project, public records only, and a bearer on it is ignored rather than
+ * honoured.
+ *
+ * The project id is the PUBLIC compound token, matching the route's own pattern
+ * and the form the tools accept; the raw regional code would not match.
+ */
+function mcpEndpointFor(
+	anonymous: boolean | undefined,
+	publicProjectId: string | undefined,
+	service: string,
+): { url: string; token?: string } {
+	if (!anonymous) return { url: mcpUrl(), token: '$ACCESS_TOKEN' };
+	const project = publicProjectId || service;
+	return { url: String(mcpUrl()).replace(/\/+$/, '') + '/p/' + project };
+}
 const clientSecretRequest = (opts: any) => chatEngineConfig().clientSecretRequest(opts);
 
 // Resolve the per-image `detail` for OpenAI. The version match tolerates a
@@ -548,7 +580,9 @@ export async function callClaudeWithPublicMcp(
 	fileUrls?: FileUrlDirective[],
 	onResponse?: (res: any) => void,
 	onError?: (err: any) => void,
+	mcpScope?: { anonymous?: boolean; publicProjectId?: string },
 ) {
+	const endpoint = mcpEndpointFor(mcpScope?.anonymous, mcpScope?.publicProjectId, service);
 	return callClaudeWithMcp({
 		prompt,
 		messages,
@@ -562,8 +596,10 @@ export async function callClaudeWithPublicMcp(
 		fileUrls,
 		mcpServer: {
 			name: MCP_NAME,
-			url: mcpUrl(),
-			authorizationToken: '$ACCESS_TOKEN',
+			url: endpoint.url,
+			// Omitted entirely for an anonymous turn; the `if (mcpServer.authorizationToken)`
+			// guard below drops the key rather than sending an empty one.
+			authorizationToken: endpoint.token,
 		},
 		onResponse,
 		onError,
@@ -582,7 +618,9 @@ export async function callOpenAIWithPublicMcp(
 	fileUrls?: FileUrlDirective[],
 	onResponse?: (res: any) => void,
 	onError?: (err: any) => void,
+	mcpScope?: { anonymous?: boolean; publicProjectId?: string },
 ) {
+	const endpoint = mcpEndpointFor(mcpScope?.anonymous, mcpScope?.publicProjectId, service);
 	const resolvedModel = model || DEFAULT_OPENAI_MODEL;
 	const imageDetail = getOpenAIImageDetail(resolvedModel);
 	const messageList =
@@ -636,11 +674,14 @@ export async function callOpenAIWithPublicMcp(
 				{
 					type: 'mcp',
 					server_label: MCP_NAME,
-					server_url: mcpUrl(),
+					server_url: endpoint.url,
 					require_approval: 'never',
-					headers: {
-						Authorization: 'Bearer $ACCESS_TOKEN',
-					},
+					// No `headers` at all for an anonymous turn: `Bearer ` with an
+					// empty token is a credential the MCP server rejects, and the
+					// project-scoped endpoint needs none.
+					...(endpoint.token
+						? { headers: { Authorization: 'Bearer ' + endpoint.token } }
+						: {}),
 				},
 				...(OPENAI_WEB_SEARCH_ENABLED
 					? [
@@ -681,6 +722,13 @@ export type AttachmentSaveInfo = {
 		mime?: string;
 		size?: number;
 		url: string;
+		/**
+		 * Access group this file's records are written at (the uploader's choice,
+		 * already applied to the "src::" record). Threaded into the indexing
+		 * prompts so the agent's own records land in the same group; omitted
+		 * means "authorized", the group everything used before the setting existed.
+		 */
+		accessGroup?: 'public' | 'authorized' | 'private';
 	};
 	/**
 	 * Content parsed CLIENT-SIDE by an attachment-parser plugin (e.g. an .hwp
@@ -892,6 +940,9 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 		projectId: info.publicProjectId || service,
 		serviceName: info.serviceName,
 		serviceDescription: info.serviceDescription,
+		// Per-FILE, not per-project: one project holds public and private files at
+		// once, so this travels on the attachment rather than the identity.
+		accessGroup: attachment.accessGroup,
 	});
 
 	if (platform === 'openai') {

package/src/engine/session.ts

@@ -798,10 +798,23 @@ export class ChatSession {
 		return 'lid_' + this._lidSeq;
 	}
 
+	/**
+	 * The key every per-chat cache hangs off: the restored message cache, the
+	 * hydrated-body memo, the live-index key and the per-file storage-path key.
+	 *
+	 * It carries the IDENTITY as well as the project and platform. A single
+	 * browser can hold more than one conversation on one project without a
+	 * reload — an anonymous visitor who signs in, or a dashboard user who logs
+	 * out and back in as someone else — and with an identity-free key the
+	 * previous conversation stayed in the cache and was re-rendered, and written
+	 * back, as the new one's. `userId` is the same value the request queue is
+	 * named after, so two identities that share a queue share a cache, which is
+	 * exactly right.
+	 */
 	getHistoryCacheKey(): string {
 		var id = this.host.getIdentity();
 		if (!id.projectId || id.platform === 'none') return '';
-		return id.projectId + '#' + id.platform;
+		return id.projectId + '#' + id.platform + '#' + (id.userId || '');
 	}
 
 	// ─── compact-stub hydration ─────────────────────────────────────────────
@@ -1059,9 +1072,17 @@ export class ChatSession {
 			if (projectId === undefined) projectId = id.projectId;
 			if (owner === undefined) owner = id.owner;
 		}
+		// Read LIVE, unlike projectId/owner above, and deliberately: this decides
+		// which MCP endpoint the turn's tools point at, and a retry after the
+		// visitor signed in should use the authenticated one rather than the
+		// project-scoped anonymous route it was composed under. Getting it wrong
+		// costs a failed turn, never a wider read: the anonymous route is
+		// read-only and public-records-only whoever calls it.
+		var liveId = this.host.getIdentity();
+		var mcpScope = { anonymous: liveId.anonymous, publicProjectId: liveId.publicProjectId };
 		return platform === 'openai'
-			? callOpenAIWithPublicMcp(prompt, projectId, owner, messages, system, model, userId, extractContent, fileUrls)
-			: callClaudeWithPublicMcp(prompt, projectId, owner, messages, system, model, userId, extractContent, fileUrls);
+			? callOpenAIWithPublicMcp(prompt, projectId, owner, messages, system, model, userId, extractContent, fileUrls, undefined, undefined, mcpScope)
+			: callClaudeWithPublicMcp(prompt, projectId, owner, messages, system, model, userId, extractContent, fileUrls, undefined, undefined, mcpScope);
 	}
 
 	dispatchAgentRequest(params: any) {
@@ -4071,6 +4092,17 @@ export class ChatSession {
 							size: member.file.size,
 						})).catch(function () { });
 					});
+					// The access group the host actually recorded this file at. Read
+					// AFTER ensureFileIndexRecord so the value here is the one the
+					// "src::" record really carries, never a second guess at it.
+					var accessGroup: 'public' | 'authorized' | 'private' | undefined;
+					preIndex = preIndex.then(function () {
+						if (alreadyIndexing) return;
+						if (typeof self.host.uploadAccessGroup !== 'function') return;
+						return Promise.resolve(self.host.uploadAccessGroup(member.storagePath))
+							.then(function (g) { accessGroup = g || undefined; })
+							.catch(function () { });
+					});
 					// Run a client-side attachment parser (e.g. .hwp) if one matches; its
 					// output is inlined into the indexing request (falls back to office
 					// extraction / web_fetch when no parser matches or it yields nothing).
@@ -4092,6 +4124,7 @@ export class ChatSession {
 						attachment: {
 							name: member.file.name, storagePath: member.storagePath,
 							mime: mime || undefined, size: member.file.size, url: url,
+							accessGroup: accessGroup,
 						},
 						parsedContent: parsedContent || undefined,
 					}).then(function (ack: any) {

package/src/widget.css

@@ -1013,6 +1013,39 @@
 }
 .bq-overwrite-applyall input { cursor: pointer; margin: 0; }
 
+/* Access-group chooser (who may read a file once it is indexed). A radio list
+   rather than a row of buttons: the three answers are not equally weighted and
+   the hint under each is what actually distinguishes them. */
+.bq-access-options {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    margin: 0 0 1rem;
+}
+.bq-access-option {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    align-items: baseline;
+    column-gap: 0.5rem;
+    padding: 0.5rem 0.6rem;
+    border: 1px solid transparent;
+    cursor: pointer;
+    user-select: none;
+}
+.bq-access-option:hover { background: var(--bq-hover-bg); }
+.bq-access-option input { cursor: pointer; margin: 0; }
+.bq-access-option-label {
+    font-size: 0.88rem;
+    color: var(--bq-ink);
+}
+.bq-access-option-hint {
+    grid-column: 2;
+    font-size: 0.76rem;
+    line-height: 1.35;
+    color: var(--bq-muted);
+    margin-top: 0.15rem;
+}
+
 /* ============================================================================
  * RESPONSIVE
  * ==========================================================================*/