bunnyquery 1.9.7 → 1.9.10

package/src/engine/index.ts

@@ -11,6 +11,23 @@ export {
 	configureChatEngine,
 	chatEngineConfig,
 	type ChatEngineConfig,
+	// The live-stream observation hook's payload. Exported so a consumer can type
+	// its handler against the engine rather than restate the shape.
+	type LiveStreamUpdate,
+	// "Can a streamed turn whose answer never reached its row be read back?" - which
+	// asks for the chunk READER and deliberately not for liveStreaming, because a
+	// row that already streamed stays recoverable long after streaming is switched
+	// off. Exported because a client with its OWN history mapper (agent.vue's fork)
+	// has to gate the `_streamPending` mark on exactly this predicate: gate it on
+	// liveStreaming and every already-streamed row is stranded the day the flag goes
+	// back off; gate it on nothing and a host with no reader gets a permanently
+	// empty bubble where it used to get none, which is strictly worse than the bug.
+	streamRecoveryEnabled,
+	// Whether a given skapi INSTANCE can carry skapi's half of the stream flag. Both
+	// clients gate their liveStreaming opt-in on it and degrade to buffered when it
+	// says no: an SDK too old to know the key drops it silently, leaving the
+	// destination streaming SSE into a buffered row that reads back empty.
+	skapiSupportsStreaming,
 } from './config';
 
 export {
@@ -47,7 +64,15 @@ export { buildChatGreeting, type ChatGreetingParams, type ChatGreetingParts } fr
 
 // Pure helpers (Tier-1.5): error detection, token budgeting, link/path
 // normalization, and history mapping — shared so both consumers stay identical.
-export { getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, isProviderApiKeyError } from './errors';
+export {
+	getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, isProviderApiKeyError,
+	// The csr-poll STATUS ENVELOPE, and the provider error nested one level inside a
+	// failed one. Exported because "is this an envelope or a body" is asked in two
+	// places that must agree (the streamed settle, and every error reader), and it
+	// was answered twice before, one of the two one level too shallow, which is how
+	// a wrong API key on a streamed turn reported "No text response received".
+	isCsrStatusEnvelope, csrEnvelopeError,
+} from './errors';
 export * from './budget';
 // Per-format UTF-8 declaration for files offered as a download. Shared so a fenced
 // block and a server-published file open identically in Excel, Word and a browser.
@@ -57,6 +82,11 @@ export * from './link_markup';
 export * from './image_preview';
 export * from './time';
 export * from './ai_agent';
+// The SSE parser. skapi relays the provider's bytes without reading them, so this is
+// where BunnyQuery's knowledge of the Anthropic and OpenAI wire formats lives. It has
+// to be on the barrel or the built engine bundle does not contain it and
+// www.skapi.com's `bunnyquery/engine` import resolves to undefined at runtime.
+export * from './sse';
 export {
 	filterListByClearHorizon,
 	normalizeTextContent,
@@ -73,6 +103,11 @@ export {
 	// rendered twice and then persisted into the history cache.
 	shouldRescueInFlightMessage,
 	type RescueDecisionContext,
+	// What the merge does when the server's copy of a turn is authoritative but
+	// EMPTY (a streamed row nobody finalized): the local answer wins, because an
+	// unknown answer is not an empty one. Shared for the same reason the rescue
+	// rule is: a client mapper that forks it erases answers off the screen.
+	adoptLocalAnswerIntoPage,
 	// One bounded look at the bg-indexing queue: which files still have a live
 	// pass. The dbfile browser's "indexed" badge uses this so a file only goes
 	// green once the run is confirmed over, not when its src:: record appears.
@@ -114,7 +149,31 @@ export {
 
 // Tier-2: the stateful chat orchestration (queue/poll/cancel, typewriter,
 // bg-task drain, resolution). DOM-free; the consumer implements ChatHost.
-export { ChatSession } from './session';
+//
+// liveSafePrefix / typewriterResumeIndex are the two pure halves of live
+// rendering: what is safe to show while the answer is still arriving, and where
+// the typewriter picks up once the authoritative answer replaces it. Exported so
+// they can be tested (and read) without a DOM.
+//
+// mayKeepStreamedAnswer is the ONE keep policy for a streamed turn: may this parse
+// be stored as the row's permanent answer, given the row's own status. It is on the
+// barrel because finalize is also the only way to release chunks, so every path
+// that can reach it has to answer this identically - the live settle and the
+// read-back once answered it separately and disagreed, and the disagreement
+// released the chunks of a failed turn.
+//
+// streamRecoveryPhase / streamRecoveryLabels are the RENDER half of the same
+// policy: given a bubble whose answer is still in the chunk store, is anything
+// actually fetching it, and if not, what does the reader get offered instead of a
+// spinner that will never resolve. Both clients read the phase from here rather
+// than from `_streamRecovery` directly - the alternative is each of them deciding
+// on its own when a loader is honest, which is precisely the fork this barrel
+// exists to prevent.
+export {
+	ChatSession, liveSafePrefix, typewriterResumeIndex, mayKeepStreamedAnswer,
+	streamRecoveryPhase, streamRecoveryLabels,
+	type StreamDispatchContext,
+} from './session';
 export type { ChatHost, ChatIdentity, ChatState, ChatMessage, IndexingFileRef, PinnedDispatchContext } from './host';
 
 // Display transform: collapse a file's many background-indexing turns into one
@@ -133,6 +192,7 @@ export {
 export {
 	// constants
 	POLL_INTERVAL,
+	STREAM_POLL_INTERVAL,
 	MAX_CONCURRENT_BG_POLLS,
 	getVisionProfile,
 	type VisionProfile,
@@ -147,6 +207,11 @@ export {
 	MCP_NAME,
 	DEFAULT_CLAUDE_MODEL,
 	DEFAULT_OPENAI_MODEL,
+	// The ONE producer of the two `stream` flags a streamed chat turn needs. Exported
+	// so a test can assert the pair moves together, which is the whole point of it
+	// being a single function.
+	chatStreamWiring,
+	type ChatStreamWiring,
 	// request builders + dispatch
 	callClaudeWithMcp,
 	callClaudeWithPublicMcp,
@@ -179,3 +244,44 @@ export {
 	type AttachmentSaveInfo,
 	type BgTaskEntry,
 } from './requests';
+
+// The project's BunnyQuery settings, stored as a public record in the customer's
+// own project ("bq::settings" in "__SETTINGS__") rather than on the skapi service
+// record. Both clients prime it when a chat page opens and await it before the
+// first upload writes an access group onto a record. See project_settings.ts.
+export {
+	// where the record lives
+	PROJECT_SETTINGS_TABLE,
+	PROJECT_SETTINGS_UNIQUE_ID,
+	PROJECT_SETTINGS_ACCESS_GROUP,
+	// the choice, its labels and its default
+	UPLOAD_ACCESS_GROUPS,
+	UPLOAD_ACCESS_LABELS,
+	UPLOAD_ACCESS_HINTS,
+	UPLOAD_ACCESS_OPTIONS,
+	DEFAULT_UPLOAD_ACCESS_GROUP,
+	// pure readers over a settings `data` object
+	normalizeUploadAccessGroup,
+	normalizeProjectAccessSetting,
+	accessSettingFrom,
+	uploadAccessGroupFrom,
+	asksUploadAccessFrom,
+	// the per-project store
+	configureProjectSettings,
+	loadProjectSettings,
+	primeProjectSettings,
+	readyProjectSettings,
+	cachedProjectSettings,
+	projectSettingsSettled,
+	projectAccessSetting,
+	projectUploadAccessGroup,
+	projectAsksUploadAccess,
+	setProjectSettings,
+	patchProjectSettings,
+	clearProjectSettings,
+	// types
+	type UploadAccessGroup,
+	type ProjectAccessSetting,
+	type ProjectSettingsData,
+	type ProjectSettingsReader,
+} from './project_settings';

package/src/engine/project_settings.ts

@@ -0,0 +1,303 @@
+/**
+ * The project's BunnyQuery settings, held as a record in the project's own
+ * database rather than on the skapi service record.
+ *
+ * WHY A RECORD. The upload access group used to live on the service record as
+ * `default_access_group`, which was ALSO the skapi SDK's project-wide default
+ * for `table.access_group`. One field meant two things: "what BunnyQuery indexes
+ * new files at" and "what every SDK record call on this project defaults to".
+ * That coupling is gone. The SDK no longer has a project default at all, so this
+ * setting needs a home of its own, and a plain public record in the customer's
+ * own project is one every client can already reach with the calls it has.
+ *
+ * SHAPE. One record per project, holding an OBJECT rather than a single value:
+ *
+ *     unique_id: 'bq::settings'
+ *     table:     { name: '__SETTINGS__', access_group: 'public' }
+ *     data:      { upload_access_group: 'authorized' }
+ *
+ * One record and one fetch covers every present and future project setting. A
+ * second setting is a new key, not a new record, so the "wait for settings
+ * before the first upload" hand-off below never has to become several waits.
+ *
+ * WHY PUBLIC. The widget reads this, and the widget frequently runs before there
+ * is any session. Group 0 is the only group an unauthenticated caller is served
+ * (`check_rec_access` returns immediately for "00" and refuses the rest). Note
+ * this is NOT sufficient on its own: skapi's `require_login` gate refuses ALL
+ * database reads from a signed-out visitor, and it defaults to true, so on most
+ * projects a signed-out widget still cannot read this and falls back to the
+ * default. That is survivable because the only thing a signed-out visitor could
+ * do with the value is upload, which they cannot do either.
+ *
+ * WHY THE VALUE MATTERS. The file BYTES are not what the access group controls.
+ * BunnyQuery uploads to db storage, whose object key carries no access group and
+ * whose read path performs no access check. What carries the group is the
+ * RECORDS: the `src::` file record in `file_summaries`, the `run::`/`done::`
+ * markers in `__INDEXING__`, and every content record the indexing agent
+ * extracts. Those are what a chat answers from, so those are what decide who the
+ * file is visible to. The same value is also handed to the chat system prompt as
+ * `indexAccessGroup`, because a record written under a different group is in a
+ * different table and never comes back with the rest of the file.
+ *
+ * TRANSPORT-FREE, like the rest of the engine. The store never imports a skapi
+ * instance; the consumer injects a reader. See configureProjectSettings.
+ */
+
+/** The access groups a BunnyQuery upload may be recorded at. */
+export type UploadAccessGroup = 'public' | 'authorized' | 'private';
+
+export const UPLOAD_ACCESS_GROUPS: UploadAccessGroup[] = ['public', 'authorized', 'private'];
+
+/**
+ * What the project's upload-access setting may be: one of the three groups the
+ * dashboard offers, or 'ask' to be prompted per upload.
+ *
+ * `'admin'` (99) is deliberately not offered: a file only a master can read is
+ * indistinguishable from one that failed to upload, and no dashboard control
+ * would produce it.
+ */
+export type ProjectAccessSetting = UploadAccessGroup | 'ask';
+
+/**
+ * `authorized` is the default because it is what every record written before
+ * this setting existed was hardcoded to. A project that never opens the setting
+ * keeps exactly the visibility it already had. It is also what the abandoned
+ * `default_access_group` service field was seeded to at project creation, so a
+ * project carrying that old value reads the same before and after the move.
+ */
+export const DEFAULT_UPLOAD_ACCESS_GROUP: UploadAccessGroup = 'authorized';
+
+/** Where the settings record lives. Shared so no client re-derives it. */
+export const PROJECT_SETTINGS_TABLE = '__SETTINGS__';
+export const PROJECT_SETTINGS_UNIQUE_ID = 'bq::settings';
+export const PROJECT_SETTINGS_ACCESS_GROUP = 'public';
+
+export const UPLOAD_ACCESS_LABELS: Record<UploadAccessGroup, string> = {
+	public: 'Public',
+	authorized: 'Signed in users',
+	private: 'Only me',
+};
+
+export const UPLOAD_ACCESS_HINTS: Record<UploadAccessGroup, string> = {
+	public: 'Anyone can ask about this file, including visitors who are not logged in.',
+	authorized: 'Only users signed in to this project can ask about this file.',
+	private: 'Only you can ask about this file.',
+};
+
+/** Menu/modal option list, in the order they should be shown. */
+export const UPLOAD_ACCESS_OPTIONS = UPLOAD_ACCESS_GROUPS.map((value) => ({
+	value,
+	label: UPLOAD_ACCESS_LABELS[value],
+	hint: UPLOAD_ACCESS_HINTS[value],
+}));
+
+/** The settings record's `data`. Open-ended: future settings are new keys. */
+export type ProjectSettingsData = {
+	upload_access_group?: unknown;
+	[key: string]: unknown;
+};
+
+/** Narrow an unknown stored value to a usable group, falling back to the default. */
+export function normalizeUploadAccessGroup(value: any): UploadAccessGroup {
+	return UPLOAD_ACCESS_GROUPS.indexOf(value) === -1
+		? DEFAULT_UPLOAD_ACCESS_GROUP
+		: (value as UploadAccessGroup);
+}
+
+/**
+ * The stored setting as written, or null when the project has never set one.
+ *
+ * Returns null rather than a default so callers can tell "unset" from "set to
+ * authorized". The settings page needs that distinction to decide what the
+ * control shows; upload paths do not and use uploadAccessGroupFrom instead.
+ */
+export function normalizeProjectAccessSetting(value: any): ProjectAccessSetting | null {
+	if (value === 'ask') return 'ask';
+	return UPLOAD_ACCESS_GROUPS.indexOf(value) === -1 ? null : (value as ProjectAccessSetting);
+}
+
+/** The setting held in a settings-record `data`, or null when unset. */
+export function accessSettingFrom(
+	data: ProjectSettingsData | null | undefined,
+): ProjectAccessSetting | null {
+	return normalizeProjectAccessSetting(data?.upload_access_group);
+}
+
+/** The group an upload lands in when the project is NOT set to 'ask'. */
+export function uploadAccessGroupFrom(
+	data: ProjectSettingsData | null | undefined,
+): UploadAccessGroup {
+	const v = accessSettingFrom(data);
+	return v && v !== 'ask' ? v : DEFAULT_UPLOAD_ACCESS_GROUP;
+}
+
+/** True when the project wants to be asked per upload rather than told once. */
+export function asksUploadAccessFrom(data: ProjectSettingsData | null | undefined): boolean {
+	return accessSettingFrom(data) === 'ask';
+}
+
+/**
+ * Fetch one project's settings record. Resolves the record's `data`, or null
+ * when there is no record.
+ *
+ * MAY REJECT, and the store treats a rejection as "no record": a signed-out
+ * visitor on a `require_login` project gets REQUIRE_LOGIN here, which is a
+ * normal outcome and not an error the user should ever see.
+ */
+export type ProjectSettingsReader = (service: string) => Promise<ProjectSettingsData | null>;
+
+type Entry = {
+	/** Resolved data, or null for "fetched, and there is none". */
+	data: ProjectSettingsData | null;
+	/** True once a fetch has SETTLED, so `data` is authoritative rather than absent. */
+	settled: boolean;
+	/** The in-flight fetch, deduped so N callers share ONE request. */
+	inflight: Promise<ProjectSettingsData | null> | null;
+};
+
+let reader: ProjectSettingsReader | null = null;
+
+/**
+ * Keyed by service id, NEVER global.
+ *
+ * One client routinely serves MANY projects: the console switches projects
+ * without reloading, and an upload outlives the page that started it. A flat
+ * single-value cache lets one project's setting decide another project's upload
+ * group, which is a silent cross-project data-visibility bug, not a stale-read
+ * annoyance. Every accessor takes the service id for this reason.
+ */
+const cache = new Map<string, Entry>();
+
+export function configureProjectSettings(fn: ProjectSettingsReader | null): void {
+	reader = fn;
+}
+
+function entry(service: string): Entry {
+	let e = cache.get(service);
+	if (!e) {
+		e = { data: null, settled: false, inflight: null };
+		cache.set(service, e);
+	}
+	return e;
+}
+
+/**
+ * Start the fetch and hand back the promise, deduping concurrent callers.
+ *
+ * Never rejects: a failed read settles as null, which every accessor reads as
+ * "unset" and answers with the default. A settings fetch must not be able to
+ * fail an upload.
+ */
+export function loadProjectSettings(service: string): Promise<ProjectSettingsData | null> {
+	if (!service) return Promise.resolve(null);
+	const e = entry(service);
+	if (e.settled) return Promise.resolve(e.data);
+	if (e.inflight) return e.inflight;
+	if (!reader) return Promise.resolve(null);
+
+	const run: Promise<ProjectSettingsData | null> = reader(service)
+		.then((data) => (data && typeof data === 'object' ? data : null))
+		.catch(() => null)
+		.then((data) => {
+			// Guard against a clear() that landed while this was in flight: the
+			// entry may have been replaced, so write through the map rather than
+			// through the captured object.
+			const cur = entry(service);
+			if (cur.inflight === run) {
+				cur.data = data;
+				cur.settled = true;
+				cur.inflight = null;
+			}
+			return data;
+		});
+
+	e.inflight = run;
+	return run;
+}
+
+/**
+ * Kick the fetch off without waiting for it. Call on chat/page open.
+ *
+ * Fire-and-forget by design: the page paints on the default and the first upload
+ * awaits the real value via readyProjectSettings. Nothing blocks on this.
+ */
+export function primeProjectSettings(service: string): void {
+	void loadProjectSettings(service);
+}
+
+/**
+ * Await the settings for this project. What the FIRST upload calls.
+ *
+ * Cheap after the first call: a settled entry resolves immediately, and a
+ * primed-but-unsettled one joins the in-flight request rather than starting a
+ * second.
+ */
+export function readyProjectSettings(service: string): Promise<ProjectSettingsData | null> {
+	return loadProjectSettings(service);
+}
+
+/**
+ * The cached data WITHOUT waiting, or null when nothing has settled yet.
+ *
+ * For synchronous readers (a template, a menu's current value). A caller that is
+ * about to WRITE an access group onto a record must use readyProjectSettings
+ * instead: answering from an unsettled cache is how a file lands in the wrong
+ * group on the first upload after a page load.
+ */
+export function cachedProjectSettings(service: string): ProjectSettingsData | null {
+	const e = cache.get(service);
+	return e && e.settled ? e.data : null;
+}
+
+/** True once this project's settings have been fetched (whether or not one existed). */
+export function projectSettingsSettled(service: string): boolean {
+	const e = cache.get(service);
+	return !!e && e.settled;
+}
+
+/** Sync convenience: the project's setting as stored, or null when unset/unsettled. */
+export function projectAccessSetting(service: string): ProjectAccessSetting | null {
+	return accessSettingFrom(cachedProjectSettings(service));
+}
+
+/** Sync convenience: the upload group, falling back to the default. */
+export function projectUploadAccessGroup(service: string): UploadAccessGroup {
+	return uploadAccessGroupFrom(cachedProjectSettings(service));
+}
+
+/** Sync convenience: does this project want a per-upload prompt? */
+export function projectAsksUploadAccess(service: string): boolean {
+	return asksUploadAccessFrom(cachedProjectSettings(service));
+}
+
+/**
+ * Adopt a value the caller just WROTE, so the settings page reflects its own
+ * save without a re-fetch.
+ *
+ * Marks the entry settled: the writer knows the stored value better than a
+ * refetch would, and leaving it unsettled would send the next upload back to the
+ * network for a value already in hand.
+ */
+export function setProjectSettings(service: string, data: ProjectSettingsData | null): void {
+	if (!service) return;
+	cache.set(service, { data: data || null, settled: true, inflight: null });
+}
+
+/** Merge one key into the cached settings, preserving the rest. */
+export function patchProjectSettings(service: string, patch: ProjectSettingsData): void {
+	if (!service) return;
+	const cur = cachedProjectSettings(service) || {};
+	setProjectSettings(service, Object.assign({}, cur, patch));
+}
+
+/**
+ * Drop cached settings. Pass a service to drop one, omit to drop all.
+ *
+ * An in-flight fetch is abandoned rather than cancelled: its `.then` checks that
+ * the entry it is writing into is still its own, so a late response cannot
+ * repopulate a cleared project.
+ */
+export function clearProjectSettings(service?: string): void {
+	if (service) cache.delete(service);
+	else cache.clear();
+}

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,7 +76,7 @@ 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.
+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.