bunnyquery 1.3.5 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunnyquery",
-  "version": "1.3.5",
+  "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> {
@@ -881,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,
@@ -893,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({
@@ -916,6 +924,7 @@ export class ChatSession {
 							att.errorDetail = (e && (e.message || (e.body && e.body.message))) || (typeof e === 'string' ? e : '');
 						}
 					});
+					});
 				});
 			});
 		});