bunnyquery 1.3.4 → 1.4.0

package/package.json

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

package/src/engine/attachment_parsers.ts

@@ -0,0 +1,112 @@
+/**
+ * Client-side attachment-parser plugins.
+ *
+ * Some attachment formats can't be read by the model's web_fetch (binary) and
+ * have no server-side extractor either — e.g. legacy Hancom .hwp. A parser
+ * plugin runs IN THE BROWSER, turns the uploaded File into indexable text (or an
+ * HTML string), and the engine sends that content INLINE in the background
+ * indexing request — so the model indexes the parsed content directly, with no
+ * upload-side server extraction and no web_fetch for that file.
+ *
+ * Register a parser with `registerAttachmentParser()`, or via
+ * `configureChatEngine({ attachmentParsers: [...] })`. The BunnyQuery widget also
+ * exposes `BunnyQuery.registerAttachmentParser()` and an `attachmentParsers`
+ * init option. First matching parser wins.
+ */
+
+export interface AttachmentParser {
+	/** Human-readable label — used only in logs. */
+	name?: string;
+	/**
+	 * Return true if this parser handles the file. Receives the file name and
+	 * (when known) its MIME type. Keep it cheap — it runs for every upload.
+	 */
+	match: (file: { name: string; mime?: string }) => boolean;
+	/**
+	 * Parse the File into indexable plain text OR an HTML string (the model reads
+	 * either). Runs in the browser; may be async. Return a falsy/empty value to
+	 * skip (the file then falls back to web_fetch / server extraction).
+	 */
+	parse: (
+		file: File,
+	) => string | null | undefined | Promise<string | null | undefined>;
+}
+
+// Hard ceiling on inlined parsed content (characters), mirroring the worker's
+// server-side MAX_EXTRACTED_CHARS, so a huge document can't blow the model's
+// context window or the request size.
+export const MAX_PARSED_CONTENT_CHARS = 200_000;
+
+const _parsers: AttachmentParser[] = [];
+
+/** Register an attachment parser. Ignores duplicates (by reference) and invalid plugins. */
+export function registerAttachmentParser(parser: AttachmentParser): void {
+	if (
+		parser &&
+		typeof parser.match === 'function' &&
+		typeof parser.parse === 'function' &&
+		_parsers.indexOf(parser) === -1
+	) {
+		_parsers.push(parser);
+	}
+}
+
+/** Remove all registered parsers (mainly for tests / re-init). */
+export function clearAttachmentParsers(): void {
+	_parsers.length = 0;
+}
+
+/** Snapshot of the registered parsers. */
+export function getAttachmentParsers(): AttachmentParser[] {
+	return _parsers.slice();
+}
+
+/** First parser whose `match` returns true for the given file, if any. */
+export function findAttachmentParser(
+	name: string,
+	mime?: string,
+): AttachmentParser | undefined {
+	for (let i = 0; i < _parsers.length; i++) {
+		try {
+			if (_parsers[i].match({ name: name, mime: mime })) return _parsers[i];
+		} catch {
+			/* a throwing matcher must not break uploads */
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Run the matching parser (if any) and return capped, trimmed content — or null
+ * when there is no parser, the parser throws, or it yields nothing. Never throws:
+ * a parser failure degrades to null so the upload still completes (the file then
+ * resolves via its normal path).
+ */
+export async function parseAttachmentContent(
+	file: File,
+	name: string,
+	mime?: string,
+): Promise<string | null> {
+	const parser = findAttachmentParser(name, mime);
+	if (!parser) return null;
+
+	let raw: string | null | undefined;
+	try {
+		raw = await parser.parse(file);
+	} catch (err) {
+		console.error(
+			`[chat-engine] attachment parser ${parser.name || '(unnamed)'} failed for ${name}:`,
+			err,
+		);
+		return null;
+	}
+
+	let text = (raw == null ? '' : String(raw)).trim();
+	if (!text) return null;
+	if (text.length > MAX_PARSED_CONTENT_CHARS) {
+		text =
+			text.slice(0, MAX_PARSED_CONTENT_CHARS) +
+			`\n...[truncated for length; original ${text.length} characters]`;
+	}
+	return text;
+}

package/src/engine/config.ts

@@ -13,6 +13,8 @@
  * send cancel). So the request builders include `poll` only when it is set.
  */
 
+import { type AttachmentParser, registerAttachmentParser } from './attachment_parsers';
+
 export interface ChatEngineConfig {
     /** skapi.clientSecretRequest, bound to the consumer's skapi instance. */
     clientSecretRequest: (opts: any) => Promise<any>;
@@ -25,12 +27,21 @@ export interface ChatEngineConfig {
      * the `poll` key is omitted entirely (agent.vue). BunnyQuery sets `0`.
      */
     poll?: number;
+    /**
+     * Optional client-side attachment parsers (e.g. an .hwp parser). Each is
+     * registered at configure time; more can be added later via
+     * `registerAttachmentParser()`. See attachment_parsers.ts.
+     */
+    attachmentParsers?: AttachmentParser[];
 }
 
 let _config: ChatEngineConfig | null = null;
 
 export function configureChatEngine(config: ChatEngineConfig): void {
     _config = config;
+    if (config.attachmentParsers) {
+        for (const parser of config.attachmentParsers) registerAttachmentParser(parser);
+    }
 }
 
 export function chatEngineConfig(): ChatEngineConfig {

package/src/engine/index.ts

@@ -26,6 +26,18 @@ export {
 	type AttachmentFailureGroup,
 } from './attachments';
 
+// Client-side attachment-parser plugins (e.g. .hwp). Register your own parser to
+// turn an uploaded File into indexable text/HTML, sent inline for indexing.
+export {
+	registerAttachmentParser,
+	clearAttachmentParsers,
+	getAttachmentParsers,
+	findAttachmentParser,
+	parseAttachmentContent,
+	MAX_PARSED_CONTENT_CHARS,
+	type AttachmentParser,
+} from './attachment_parsers';
+
 export * from './prompts';
 
 // Pure helpers (Tier-1.5): error detection, token budgeting, link/path

package/src/engine/office.ts

@@ -21,24 +21,46 @@ export type ExtractDirective = {
 	mime?: string;
 };
 
-// Office formats whose text the model cannot read via web_fetch. OOXML
-// (.docx/.xlsx/.pptx) and Hancom .hwpx are extracted server-side; the other
-// (legacy/macro/binary) extensions are still flagged so the worker returns a
-// graceful note instead of the model fetching binary garbage.
+// Binary/zip document formats the model cannot read via web_fetch. OOXML
+// (.docx/.xlsx/.pptx), Hancom .hwpx, OpenDocument (.ods/.odt/.odp), and EPUB
+// (.epub) are extracted server-side; the other (legacy/macro/binary) extensions
+// are still flagged so the worker returns a graceful note instead of the model
+// fetching binary garbage.
 const OFFICE_FILE_EXTENSIONS = new Set([
 	'doc', 'docx', 'docm',
 	'xls', 'xlsx', 'xlsm',
 	'ppt', 'pptx', 'pptm',
 	'hwp', 'hwpx',
+	'ods', 'odt', 'odp',
+	'epub',
+]);
+
+// Plain-text/data formats web_fetch CAN read. These must NEVER be treated as
+// office files even when the OS/browser reports an Office MIME for them — most
+// notably .csv, which Windows/Excel reports as `application/vnd.ms-excel`. The
+// extension is authoritative here; without this guard a .csv is wrongly flagged
+// for server-side extraction, the worker can't extract `.csv`, and the model
+// gets an "unsupported format" note instead of the file's contents.
+const WEB_FETCHABLE_TEXT_EXTENSIONS = new Set([
+	'csv', 'tsv', 'tab', 'txt', 'text', 'md', 'markdown',
+	'json', 'ndjson', 'jsonl', 'xml', 'yaml', 'yml', 'log',
+	// RTF is a TEXT format (not a binary zip), so web_fetch can read it and the
+	// model decodes its control words. Pin it here so a `.rtf` reported as
+	// `application/msword` isn't misrouted to server-side extraction (which has no
+	// .rtf extractor → "unsupported format" note).
+	'rtf', 'htm', 'html',
 ]);
 
 export function isOfficeFile(name?: string, mime?: string): boolean {
 	const ext = (name || '').split('.').pop()?.toLowerCase() || '';
 	if (OFFICE_FILE_EXTENSIONS.has(ext)) return true;
+	if (WEB_FETCHABLE_TEXT_EXTENSIONS.has(ext)) return false;
 	const m = (mime || '').toLowerCase();
 	return (
 		m.includes('officedocument') ||
+		m.includes('opendocument') ||
 		m.includes('hwp') ||
+		m.includes('epub') ||
 		m === 'application/msword' ||
 		m === 'application/vnd.ms-excel' ||
 		m === 'application/vnd.ms-powerpoint'

package/src/engine/prompts/indexing_user_message.ts

@@ -30,6 +30,12 @@ export type BuildIndexingUserMessageOptions = {
 	 * drops the temporary-URL line — there is nothing for the model to fetch).
 	 */
 	inlineContentPlaceholder?: string;
+	/**
+	 * Actual file content parsed CLIENT-SIDE by an attachment-parser plugin (e.g.
+	 * an .hwp parser). Embedded inline verbatim — no server extraction and no
+	 * web_fetch for this file. Takes precedence over `inlineContentPlaceholder`.
+	 */
+	inlineContent?: string;
 };
 
 export function buildIndexingUserMessage(
@@ -44,6 +50,20 @@ export function buildIndexingUserMessage(
 		(attachment.mime ? `- mime type: ${attachment.mime}\n` : '') +
 		(typeof attachment.size === 'number' ? `- size (bytes): ${attachment.size}\n` : '');
 
+	if (options?.inlineContent) {
+		// Parsed client-side (an attachment-parser plugin). The content is already
+		// inlined below — no server extraction, no URL to fetch.
+		return (
+			head +
+			`\nThe file's content was parsed by the client and is provided inline below. ` +
+			`Read it directly — do NOT fetch any URL for this file. ` +
+			`Use the storage path above (not this content) for the "src::" unique_id.\n\n` +
+			`----- BEGIN FILE CONTENT -----\n` +
+			`${options.inlineContent}\n` +
+			`----- END FILE CONTENT -----`
+		);
+	}
+
 	if (options?.inlineContentPlaceholder) {
 		// Office file: text was extracted on the server and is inlined below
 		// between the markers. Do NOT fetch any URL for this file.

package/src/engine/requests.ts

@@ -425,14 +425,22 @@ export type AttachmentSaveInfo = {
 		size?: number;
 		url: string;
 	};
+	/**
+	 * Content parsed CLIENT-SIDE by an attachment-parser plugin (e.g. an .hwp
+	 * parser). When set, it is inlined into the indexing message verbatim and
+	 * takes precedence over server-side office extraction / web_fetch.
+	 */
+	parsedContent?: string;
 };
 
-// Background "save into knowledge" call (not a chat turn). Office files get the
-// _skapi_extract directive + an inline-content placeholder instead of a URL.
+// Background "save into knowledge" call (not a chat turn). A client-parsed file
+// (parser plugin) is inlined directly; otherwise office files get the
+// _skapi_extract directive + a placeholder, and everything else gets a URL.
 export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
-	const { platform, service, owner, attachment } = info;
+	const { platform, service, owner, attachment, parsedContent } = info;
 
-	const office = isOfficeFile(attachment.name, attachment.mime);
+	// Client-parsed content wins over server-side office extraction.
+	const office = !parsedContent && isOfficeFile(attachment.name, attachment.mime);
 	const placeholder = office ? makeExtractPlaceholder(attachment.storagePath) : undefined;
 	const extractContent: ExtractDirective[] | undefined =
 		office && placeholder
@@ -443,7 +451,11 @@ export async function notifyAgentSaveAttachment(info: AttachmentSaveInfo) {
 
 	const userMessage = buildIndexingUserMessage(
 		attachment,
-		placeholder ? { inlineContentPlaceholder: placeholder } : undefined,
+		parsedContent
+			? { inlineContent: parsedContent }
+			: placeholder
+				? { inlineContentPlaceholder: placeholder }
+				: undefined,
 	);
 
 	const systemPrompt = buildIndexingSystemPrompt({

package/src/engine/session.ts

@@ -34,6 +34,7 @@ import { isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, ge
 import { buildBoundedChatMessages } from './budget';
 import { createInlineLinkRegex } from './links';
 import { mapHistoryListToMessages, extractLastUserTextFromRequest } from './history';
+import { parseAttachmentContent } from './attachment_parsers';
 import type { ChatHost, ChatState, ChatMessage } from './host';
 
 function sleep(ms: number): Promise<void> {
@@ -352,6 +353,7 @@ export class ChatSession {
 				this.host.notify(); this.enqueueTypewrite(aiIdx, answer, lid);
 			}
 		}
+		this._removeStrayPendingAssistants();
 		this.promoteNextQueuedToRunning();
 		this.updateHistoryCache();
 		this.host.notify();
@@ -386,12 +388,14 @@ export class ChatSession {
 				if (thPos2 !== -1) this.state.messages.splice(thPos2, 1);
 			}
 			if (serverId) this.cancelledServerIds.delete(serverId);
+			this._removeStrayPendingAssistants();
 			this.promoteNextQueuedToRunning(); this.updateHistoryCache(); this.host.notify(); this.host.scrollToBottom(true);
 			return;
 		}
 		var targetIdx = this.resolveQueuedUserBubble(serverId);
 		if (targetIdx === undefined) { this.host.notify(); this.updateHistoryCache(); return; }
 		this.insertAtTarget({ role: 'assistant', content: getErrorMessage(err), isError: true }, targetIdx);
+		this._removeStrayPendingAssistants();
 		this.promoteNextQueuedToRunning(); this.updateHistoryCache(); this.host.notify(); this.host.scrollToBottom(true);
 	}
 
@@ -516,17 +520,52 @@ export class ChatSession {
 		if (pendingIdx === -1) return Promise.resolve();
 		if (latest.isError || !latest.content) {
 			this.state.messages[pendingIdx] = { role: 'assistant', content: latest.content || '', isError: !!latest.isError };
+			this._removeStrayPendingAssistants();
 			this.host.notify();
 			this.promoteNextQueuedToRunning();
 			return Promise.resolve();
 		}
 		var lid = this._newLocalId();
 		this.state.messages[pendingIdx] = { role: 'assistant', content: '', isPending: false, _localId: lid };
+		this._removeStrayPendingAssistants();
 		this.host.notify();
 		this.promoteNextQueuedToRunning();
 		return this.enqueueTypewrite(pendingIdx, latest.content, lid);
 	}
 
+	// Remove any leftover non-background pending ("Thinking…") assistant bubbles.
+	// There is normally at most ONE such bubble at a time (promoteNext* refuses to
+	// add a second), so any extra is a duplicate — it appears when a concurrent
+	// history refetch re-maps the still-"running" turn into a pending placeholder
+	// (with a real _serverItemId) while the local pending bubble (no _serverItemId)
+	// is rescued and re-appended (see loadHistory rescue below). Each resolve path
+	// only replaces the FIRST pending bubble, so without this a stray "Thinking…"
+	// survives next to the reply/error. MUST run AFTER the resolved bubble has been
+	// made non-pending and BEFORE promoteNext*() (so a freshly-promoted Thinking,
+	// which is added only once no pending assistant remains, is preserved).
+	_removeStrayPendingAssistants(): void {
+		for (var k = this.state.messages.length - 1; k >= 0; k--) {
+			var m = this.state.messages[k];
+			if (m.isPending && m.role === 'assistant' && !m.isBackgroundTask) this.state.messages.splice(k, 1);
+		}
+	}
+
+	// Drop the pending flags on the resolved turn's USER bubble (preserving its
+	// content + background-task marker). Needed because a bg "Indexing:" turn's user
+	// bubble carries isPendingInProcess; leaving it set keeps the bubble visually
+	// stuck and keeps its bgTaskQueue entry alive forever.
+	_clearPendingUserBubble(itemId: string): void {
+		var uIdx = this.state.messages.findIndex(function (m) {
+			return m.role === 'user' && m._serverItemId === itemId &&
+				(m.isPendingInProcess || m.isPendingQueued || m.isSendingToServer);
+		});
+		if (uIdx === -1) return;
+		var u = this.state.messages[uIdx];
+		var cleaned: ChatMessage = { role: 'user', content: u.content, _serverItemId: itemId };
+		if (u.isBackgroundTask) cleaned.isBackgroundTask = true;
+		this.state.messages[uIdx] = cleaned;
+	}
+
 	// If an immediate-send request for the current cache key is still in flight
 	// (e.g. the view unmounted then remounted mid-request), show the sending
 	// state, await it, then render the reply from the cache. Skipped when the
@@ -561,6 +600,11 @@ export class ChatSession {
 			: ((platform === 'openai' ? extractOpenAIText(response) : extractClaudeText(response)) || '').trim();
 		var idx = this.state.messages.findIndex(function (m) { return m.isPending && m._serverItemId === itemId; });
 		if (idx !== -1) {
+			// A bg "Indexing:" turn pushes a user bubble (isPendingInProcess) ALONGSIDE
+			// the assistant Thinking; replacing only the assistant leaves that user
+			// bubble stuck pending — and drainBgTaskQueue then never clears its queue
+			// entry (its stillPending check stays true). Un-pend it here too.
+			this._clearPendingUserBubble(itemId);
 			if (isErr) {
 				this.state.messages[idx] = { role: 'assistant', content: answer, isError: true, _serverItemId: itemId };
 				this.host.notify(); this.updateHistoryCache(); return;
@@ -690,12 +734,23 @@ export class ChatSession {
 				mapped.forEach(function (m: any) { if (m._serverItemId) serverIds[m._serverItemId] = 1; });
 				var locallyCancelled: any = {};
 				self.state.messages.forEach(function (m) { if (m.isCancelled && m._serverItemId) locallyCancelled[m._serverItemId] = 1; });
+				// If the freshly-mapped server list ALREADY shows this in-flight turn
+				// as a pending placeholder (a non-bg pending assistant, which carries
+				// a real _serverItemId), re-pushing the local no-_serverItemId
+				// user+Thinking would DUPLICATE it. Each resolve path only clears the
+				// first pending bubble, so the duplicate strands a "Thinking…" beside
+				// the reply/error. There is at most one in-flight regular turn, so a
+				// mapped pending assistant IS this turn — skip the redundant local copy.
+				var mappedHasPendingAssistant = mapped.some(function (m: any) {
+					return m.isPending && m.role === 'assistant' && !m.isBackgroundTask;
+				});
 				var rescued: ChatMessage[] = [];
 				for (var ri = 0; ri < self.state.messages.length; ri++) {
 					var mm = self.state.messages[ri];
 					if (mm.isBackgroundTask) continue;
 					if (mm._serverItemId && serverIds[mm._serverItemId]) continue;
 					if (!mm._serverItemId) {
+						if (mappedHasPendingAssistant) continue;
 						if (mm.isSendingToServer || mm.isPendingQueued || mm.isPendingInProcess || mm.isPending) rescued.push(mm);
 						else if (self.state.sending && mm.role === 'user') {
 							var next = self.state.messages[ri + 1];
@@ -827,6 +882,12 @@ export class ChatSession {
 					urls.push({ name: member.relPath, url: url, storagePath: member.storagePath });
 					if (att.kind !== 'folder') { att.uploadedUrl = url; att.storagePath = member.storagePath; }
 					var mime = member.file.type || self.host.getMimeType(member.file.name);
+					// 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).
+					return Promise.resolve(
+						parseAttachmentContent(member.file, member.file.name, mime || undefined),
+					).then(function (parsedContent: string | null) {
 					return notifyAgentSaveAttachment({
 						platform: id.platform as 'claude' | 'openai',
 						model: id.model,
@@ -839,6 +900,7 @@ export class ChatSession {
 							name: member.file.name, storagePath: member.storagePath,
 							mime: mime || undefined, size: member.file.size, url: url,
 						},
+						parsedContent: parsedContent || undefined,
 					}).then(function (ack: any) {
 						if (ack && typeof ack.id === 'string') {
 							self.bgTaskQueue.push({
@@ -862,6 +924,7 @@ export class ChatSession {
 							att.errorDetail = (e && (e.message || (e.body && e.body.message))) || (typeof e === 'string' ? e : '');
 						}
 					});
+					});
 				});
 			});
 		});