bunnyquery 1.2.2 → 1.3.0

package/src/engine/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Error detection + message extraction (pure). Moved verbatim from the
+ * agent.vue / bunnyquery chatbox so both consumers share one implementation.
+ */
+
+export function getErrorMessage(input: any): string {
+	if (!input) return 'Something went wrong.';
+	if (typeof input === 'string') return input;
+	if (input.error && input.error.message) return input.error.message;
+	if (input.body && input.body.error && input.body.error.message) return input.body.error.message;
+	if (input.body && typeof input.body.message === 'string') return input.body.message;
+	if (input.message) return input.message;
+	return 'Something went wrong.';
+}
+
+export function isErrorResponseBody(response: any): boolean {
+	if (!response || typeof response !== 'object') return false;
+	if (typeof response.status_code === 'number' && response.status_code >= 400) return true;
+	if (response.type === 'error') return true;
+	if (response.error && (response.error.message || response.error.type)) return true;
+	var body = response.body;
+	if (body && typeof body === 'object') {
+		if (body.type === 'error') return true;
+		if (body.error && (body.error.message || body.error.type)) return true;
+	}
+	if (typeof response.message === 'string' && response.message.length) {
+		var hasClaude = Array.isArray(response.content);
+		var hasOpenAI =
+			typeof response.output_text === 'string' ||
+			Array.isArray(response.output) ||
+			Array.isArray(response.choices);
+		if (!hasClaude && !hasOpenAI) return true;
+	}
+	return false;
+}
+
+export function isAuthExpiredError(input: any): boolean {
+	if (!input) return false;
+	var blobs: string[] = [];
+	var push = function (v: any) { if (typeof v === 'string' && v) blobs.push(v); };
+	if (typeof input === 'string') push(input);
+	else {
+		push(input.message); push(input.code);
+		if (input.error) { push(input.error.message); push(input.error.code); push(input.error.type); }
+		if (input.body) {
+			push(input.body.message);
+			if (input.body.error) { push(input.body.error.message); push(input.body.error.code); push(input.body.error.type); }
+		}
+		if (typeof input.status === 'number' && input.status === 401) return true;
+		if (typeof input.status_code === 'number' && input.status_code === 401) return true;
+	}
+	var hay = blobs.join(' | ').toLowerCase();
+	if (!hay) return false;
+	return hay.indexOf('token has expired') !== -1 || hay.indexOf('token is expired') !== -1 ||
+		hay.indexOf('expired_token') !== -1 || hay.indexOf('invalid_token') !== -1 ||
+		hay.indexOf('unauthorized') !== -1 || hay.indexOf('not authorized') !== -1 ||
+		(hay.indexOf('invalid_request') !== -1 && hay.indexOf('token') !== -1);
+}

package/src/engine/history.ts

@@ -0,0 +1,117 @@
+/**
+ * History mapping (pure). Moved verbatim from the chatbox. The clear-horizon
+ * timestamp and the "Indexing: …" display label are INJECTED (clearedAt param,
+ * formatIndexingLabel callback) so the engine touches neither localStorage nor
+ * view-specific display formatting. serviceId is passed for link sanitization.
+ */
+import { extractClaudeText, extractOpenAIText } from './requests';
+import { isErrorResponseBody, getErrorMessage } from './errors';
+import { sanitizeAttachmentLinksForHistory } from './links';
+
+export function filterListByClearHorizon(list: any[], clearedAt: number): any[] {
+	if (!clearedAt) return list;
+	return list.filter(function (item) {
+		var updated = Number(item && item.updated);
+		return isFinite(updated) && updated > clearedAt;
+	});
+}
+
+export function normalizeTextContent(content: any): string {
+	if (typeof content === 'string') return content;
+	if (Array.isArray(content)) {
+		return content.map(function (part: any) {
+			if (typeof part === 'string') return part;
+			if (part && (part.type === 'text' || part.type === 'input_text' || part.type === 'output_text')) return part.text || '';
+			return '';
+		}).join('\n').trim();
+	}
+	return '';
+}
+
+export function extractLastUserTextFromRequest(requestBody: any): string {
+	var arr = requestBody && Array.isArray(requestBody.messages) ? requestBody.messages
+		: (requestBody && Array.isArray(requestBody.input) ? requestBody.input : []);
+	for (var i = arr.length - 1; i >= 0; i--) {
+		if (arr[i] && arr[i].role === 'user') {
+			var t = normalizeTextContent(arr[i].content);
+			if (t) return t;
+		}
+	}
+	return '';
+}
+
+export type MapHistoryOptions = {
+	clearedAt: number;
+	serviceId: string;
+	/** View-side display formatter for "Indexing:/Reindexing: …" bubbles. */
+	formatIndexingLabel: (name: string, mime?: string, size?: number | null, storagePath?: string) => string;
+};
+
+export function mapHistoryListToMessages(list: any[], platform: 'claude' | 'openai', opts: MapHistoryOptions) {
+	var mapped: any[] = [], runningItemIds: string[] = [];
+	var extractAssistantText = platform === 'openai' ? extractOpenAIText : extractClaudeText;
+	var filtered = filterListByClearHorizon(list, opts.clearedAt);
+	filtered.slice().reverse().forEach(function (item) {
+		var requestBody = item && item.request_body;
+		var isInProcess = item && item.status === 'running';
+		var isQueued = item && item.status === 'pending';
+		var isCancelledItem = item && item.status === 'cancelled';
+		var isPending = isInProcess || isQueued;
+		var isFailed = item && item.status === 'failed';
+		var response = isFailed ? (item.error != null ? item.error : item.response_body)
+			: (item && item.response_body != null ? item.response_body : item && item.error);
+		var userText = extractLastUserTextFromRequest(requestBody);
+		var assistantText = isPending ? '' : ((extractAssistantText(response) || '').trim() || '');
+		var isErrorResponse = !isPending && (isFailed || isErrorResponseBody(response));
+		var serverItemId = item && typeof item.id === 'string' && item.id ? item.id : undefined;
+
+		if (userText) {
+			var displayContent;
+			if (item._isBgTask) {
+				var nameMatch = userText.match(/^- name: (.+)$/m);
+				if (nameMatch) {
+					var mimeMatch = userText.match(/^- mime type: (.+)$/m);
+					var sizeMatch = userText.match(/^- size \(bytes\): (\d+)$/m);
+					var pathMatch = userText.match(/^- storage path: (.+)$/m);
+					displayContent = opts.formatIndexingLabel(
+						nameMatch[1].trim(),
+						mimeMatch ? mimeMatch[1].trim() : '',
+						sizeMatch ? Number(sizeMatch[1]) : null,
+						pathMatch ? pathMatch[1].trim() : undefined
+					);
+				} else {
+					displayContent = userText;
+				}
+			} else {
+				displayContent = sanitizeAttachmentLinksForHistory(userText, opts.serviceId);
+			}
+			var userMsg: any = { role: 'user', content: displayContent };
+			if (isInProcess) userMsg.isPendingInProcess = true;
+			if (isQueued) userMsg.isPendingQueued = true;
+			if (isCancelledItem) userMsg.isCancelled = true;
+			if (item._isBgTask) userMsg.isBackgroundTask = true;
+			if (item._isOnBgQueue) userMsg._useBgQueue = true;
+			if (serverItemId !== undefined) userMsg._serverItemId = serverItemId;
+			mapped.push(userMsg);
+		}
+		if (isCancelledItem) { /* no assistant bubble */ }
+		else if (isInProcess) {
+			var ph: any = { role: 'assistant', content: '', isPending: true, isPendingInProcess: true };
+			if (item._isBgTask) ph.isBackgroundTask = true;
+			if (serverItemId !== undefined) { ph._serverItemId = serverItemId; runningItemIds.push(serverItemId); }
+			mapped.push(ph);
+		} else if (isQueued) { /* no assistant placeholder */ }
+		else if (isErrorResponse) {
+			var em: any = { role: 'assistant', content: getErrorMessage(response), isError: true };
+			if (item._isBgTask) em.isBackgroundTask = true;
+			if (serverItemId !== undefined) em._serverItemId = serverItemId;
+			mapped.push(em);
+		} else if (assistantText) {
+			var okm: any = { role: 'assistant', content: assistantText };
+			if (item._isBgTask) okm.isBackgroundTask = true;
+			if (serverItemId !== undefined) okm._serverItemId = serverItemId;
+			mapped.push(okm);
+		}
+	});
+	return { messages: mapped, runningItemIds: runningItemIds };
+}

package/src/engine/host.ts

@@ -0,0 +1,110 @@
+/**
+ * ChatSession host adapter + state types.
+ *
+ * ChatSession is DOM-free and Vue-free; the consumer (bunnyquery widget or the
+ * agent.vue chatbox) implements `ChatHost` to bridge identity, rendering, scroll,
+ * and the skapi cancel/refresh surface. Everything the session needs that would
+ * otherwise touch the DOM or a framework goes through a host hook.
+ */
+
+export interface ChatIdentity {
+	serviceId: string;
+	owner: string;
+	/** Per-user queue name (falls back to serviceId). */
+	userId: string;
+	platform: 'claude' | 'openai' | 'none';
+	model?: string;
+	serviceName?: string;
+	serviceDescription?: string;
+}
+
+export interface ChatMessage {
+	role: 'user' | 'assistant';
+	content: string; // raw markdown — never HTML (the view parses for display)
+	isPending?: boolean;
+	isPendingInProcess?: boolean;
+	isPendingQueued?: boolean;
+	isPendingOlder?: boolean;
+	isSendingToServer?: boolean;
+	isCancelled?: boolean;
+	isError?: boolean;
+	isBackgroundTask?: boolean;
+	_useBgQueue?: boolean;
+	_serverItemId?: string;
+	_localId?: string;
+	_cancelling?: boolean;
+	_cancelError?: string;
+}
+
+export interface ChatState {
+	messages: ChatMessage[];
+	/** Pending/uploaded attachment objects (view-shaped); the engine mutates
+	 *  status/progress during upload, the view renders them. */
+	attachments: any[];
+	uploadingAttachments: boolean;
+	sending: boolean;
+	typing: boolean;
+	typingAbort: boolean;
+	loadingHistory: boolean;
+	loadingOlderHistory: boolean;
+	historyEndOfList: boolean;
+	historyStartKeyHistory: string[];
+	historyRequestToken: number;
+	gateRefreshToken: number;
+}
+
+export interface ChatHost {
+	/** Read live (platform/model/name can change between sends). */
+	getIdentity(): ChatIdentity;
+	/** The chat system prompt (consumer-built; agent.vue uses a formatted id). */
+	buildSystemPrompt(): string;
+
+	// --- render / scroll (the ONLY view surface) ---
+	/** Re-render the whole message list (coalesced). */
+	notify(): void;
+	/** Re-render a single message bubble in place (typewriter ticks). */
+	refreshMessageBubble(idx: number): void;
+	scrollToBottom(smooth?: boolean): Promise<void> | void;
+	/** Scroll only if the user is pinned to the bottom (does not force-pin). */
+	scrollToBottomIfSticky(smooth?: boolean): Promise<void> | void;
+
+	// --- skapi surface beyond configureChatEngine() ---
+	cancelRequest(opts: {
+		url: string; method: string; id: string; queue: string; service: string; owner: string;
+	}): Promise<{ removed?: boolean; message?: string } | any>;
+	refreshSession(): Promise<boolean>;
+
+	// --- bg-indexing display ---
+	/** Build the "Indexing:/Reindexing: …" label (view-side display formatting). */
+	formatIndexingLabel(name: string, mime?: string, size?: number | null, storagePath?: string, reindex?: boolean): string;
+	/** drainBgTaskQueue is a no-op until the chat view is mounted. */
+	isViewMounted(): boolean;
+
+	/** Clear-horizon timestamp (localStorage, per service#platform) — view-owned. */
+	getClearedAt(): number;
+
+	// --- attachment upload I/O (consumer-specific bytes path: agent.vue uses the
+	//     Service class, bunnyquery uses get-signed-url). The session owns the
+	//     upload ORCHESTRATION (per-member loop, overwrite/reindex flow, indexing,
+	//     status lifecycle); these hooks do the actual I/O + chip rendering. ---
+	uploadFile(args: {
+		file: File;
+		storagePath: string;
+		checkExistence: boolean;
+		onProgress?: (p: any) => void;
+		setAbort?: (abort: () => void) => void;
+	}): Promise<any>;
+	/** Mint a temporary CDN URL for a stored file. */
+	getTemporaryUrl(storagePath: string): Promise<string>;
+	/** Map a relative path to the consumer's db storage key (e.g. uid-prefixed). */
+	storagePathFor(relPath: string): string;
+	getMimeType(name: string): string | null;
+	/** Non-dismissible "file exists" prompt → keep+reindex vs overwrite. */
+	promptOverwrite(filename: string): Promise<'overwrite' | 'reindex'>;
+	/** Clear the "apply to all" overwrite choice at the start of a batch. */
+	resetOverwriteBatch(): void;
+	/** Re-render the attachment chip row (progress / status). */
+	renderAttachmentChips(): void;
+	/** Enable/disable composer controls during an upload batch. */
+	updateComposerControls(): void;
+}

package/src/engine/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @skapi/chat-engine — framework-agnostic chat engine.
+ *
+ * Tier-1 (this barrel): pure transport/logic shared by agent.vue and the
+ * BunnyQuery widget. DOM-free and Vue-free. Consumers inject the skapi
+ * transport + MCP base URL via configureChatEngine() and (for markdown / DOM
+ * rendering) keep their own view layer.
+ */
+
+export {
+	configureChatEngine,
+	chatEngineConfig,
+	type ChatEngineConfig,
+} from './config';
+
+export {
+	isOfficeFile,
+	makeExtractPlaceholder,
+	composeUserMessage,
+	type ExtractDirective,
+	type ComposedUserMessage,
+} from './office';
+
+export * from './prompts';
+
+// 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 } from './errors';
+export * from './budget';
+export * from './links';
+export {
+	filterListByClearHorizon,
+	normalizeTextContent,
+	extractLastUserTextFromRequest,
+	mapHistoryListToMessages,
+	type MapHistoryOptions,
+} from './history';
+
+// Tier-2: the stateful chat orchestration (queue/poll/cancel, typewriter,
+// bg-task drain, resolution). DOM-free; the consumer implements ChatHost.
+export { ChatSession } from './session';
+export type { ChatHost, ChatIdentity, ChatState, ChatMessage } from './host';
+
+export {
+	// constants
+	POLL_INTERVAL,
+	BG_INDEXING_QUEUE_SUFFIX,
+	MCP_NAME,
+	DEFAULT_CLAUDE_MODEL,
+	DEFAULT_OPENAI_MODEL,
+	// request builders + dispatch
+	callClaudeWithMcp,
+	callClaudeWithPublicMcp,
+	callOpenAIWithPublicMcp,
+	notifyAgentSaveAttachment,
+	listClaudeModels,
+	listOpenAIModels,
+	getChatHistory,
+	// response extraction
+	extractClaudeText,
+	extractOpenAIText,
+	// content transforms
+	transformContentWithImages,
+	transformContentWithOpenAIImages,
+	// types
+	type ClaudeRole,
+	type ClaudeMessage,
+	type OpenAIMessage,
+	type ClaudeMcpToolConfig,
+	type ClaudeMcpServerRequest,
+	type CallClaudeWithMcpParams,
+	type AttachmentSaveInfo,
+	type BgTaskEntry,
+} from './requests';

package/src/engine/links.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure link/path helpers (no DOM, no marked). Moved verbatim from the chatbox.
+ * `serviceId` is passed as a PARAMETER (the original read it from a global) so
+ * the engine stays consumer-agnostic. The HTML-emitting helpers
+ * (buildLinkPartFromGroups, linkToAnchorHtml, fileToAnchorHtml, parseMsgParts*)
+ * stay in each VIEW — only these pure pieces move here.
+ */
+
+export var EXPIRED_ATTACHMENT_URL_HOST = '_expired_.url';
+export var EXPIRED_ATTACHMENT_URL_ORIGIN = 'https://' + EXPIRED_ATTACHMENT_URL_HOST;
+export var LINK_LABEL_MAX_DISPLAY_CHARS = 32;
+
+export function createInlineLinkRegex(): RegExp {
+	return /src::(\S+)|\[([^\]\n]+)\]\((https?:\/\/(?:[^\s()]+|\([^\s()]*\))+)\)|\[([^\]\n]+)\]\(((?:[^()\n]+|\([^()\n]*\))+)\)|(https?:\/\/[^\s<>"']+)/g;
+}
+
+export function safeDecodeURIComponent(v: string): string {
+	try { return decodeURIComponent(v); } catch (e) { return v; }
+}
+
+export function encodePathSegments(path: string): string {
+	return path.split('/').filter(Boolean).map(function (s) { return encodeURIComponent(s); }).join('/');
+}
+
+export function normalizeAttachmentPathCandidate(value: string): string {
+	return safeDecodeURIComponent((value || '').trim()).replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/');
+}
+
+export function extractRemotePathFromAttachmentHref(href: string, serviceId: string): string | null {
+	try {
+		var parsed = new URL(href);
+		if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+		var path = normalizeAttachmentPathCandidate(parsed.pathname || '');
+		var segs = path.split('/').filter(Boolean);
+		if (!segs.length) return null;
+		var HEX = /^[a-f0-9]{32,}$/i;
+		var sid = serviceId || '';
+		var start = 0;
+		while (start < segs.length) {
+			var seg = segs[start];
+			if (seg === sid || HEX.test(seg)) { start++; continue; }
+			break;
+		}
+		var real = segs.slice(start).join('/');
+		return real || null;
+	} catch (e) { return null; }
+}
+
+export function getExpiredAttachmentVisiblePath(remotePath: string, fallback?: string): string {
+	var n = normalizeAttachmentPathCandidate(remotePath);
+	if (n) return n;
+	return normalizeAttachmentPathCandidate(fallback || 'file') || 'file';
+}
+
+export function buildDisplayExpiredAttachmentHref(remotePath: string, fallback?: string): string {
+	return EXPIRED_ATTACHMENT_URL_ORIGIN + '/' + encodePathSegments(getExpiredAttachmentVisiblePath(remotePath, fallback));
+}
+
+export function sanitizeAttachmentLinksForHistory(content: string, serviceId: string): string {
+	if (!content || content.indexOf('Attached files:') === -1) return content;
+	return content.replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)/g, function (_m: string, label: string, href: string) {
+		var remotePath = extractRemotePathFromAttachmentHref(href, serviceId);
+		var labelPath = normalizeAttachmentPathCandidate(label);
+		var fullPath = remotePath || labelPath;
+		if (!fullPath) return '[' + label + '](' + EXPIRED_ATTACHMENT_URL_ORIGIN + '/file)';
+		return '[' + label + '](' + buildDisplayExpiredAttachmentHref(fullPath, label) + ')';
+	});
+}
+
+export function truncateLabelForDisplay(label: string): string {
+	if (!label) return label;
+	if (label.length <= LINK_LABEL_MAX_DISPLAY_CHARS) return label;
+	return '…' + label.slice(label.length - (LINK_LABEL_MAX_DISPLAY_CHARS - 1));
+}

package/src/engine/office.ts

@@ -0,0 +1,105 @@
+/**
+ * Office-file server-side extraction helpers.
+ *
+ * Office documents (Microsoft .docx/.xlsx/.pptx, Hancom .hwpx, etc.) can't be
+ * read by web_fetch (binary/zip). The proxy worker downloads them from db
+ * storage, extracts their text server-side, and substitutes that text for a
+ * placeholder token in the request body (carried under the reserved
+ * `_skapi_extract` key, which the producer strips before the upstream call).
+ */
+
+// A directive telling the proxy worker which office file to download + extract
+// and which placeholder token in the request body to substitute.
+export type ExtractDirective = {
+	/** db storage path of the file, e.g. "folder/report.docx" (also the src:: value). */
+	path: string;
+	/** The exact token in the request body to replace with the extracted text. */
+	placeholder: string;
+	/** Original filename — informational (server logs only). */
+	name?: string;
+	/** MIME type — informational (server logs only). */
+	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.
+const OFFICE_FILE_EXTENSIONS = new Set([
+	'doc', 'docx', 'docm',
+	'xls', 'xlsx', 'xlsm',
+	'ppt', 'pptx', 'pptm',
+	'hwp', 'hwpx',
+]);
+
+export function isOfficeFile(name?: string, mime?: string): boolean {
+	const ext = (name || '').split('.').pop()?.toLowerCase() || '';
+	if (OFFICE_FILE_EXTENSIONS.has(ext)) return true;
+	const m = (mime || '').toLowerCase();
+	return (
+		m.includes('officedocument') ||
+		m.includes('hwp') ||
+		m === 'application/msword' ||
+		m === 'application/vnd.ms-excel' ||
+		m === 'application/vnd.ms-powerpoint'
+	);
+}
+
+// Monotonic counter so placeholders are unique even for same-named files in one
+// request. Token shape must match the worker's _EXTRACT_PLACEHOLDER_RE:
+// {{SKAPI_FILE_CONTENT::<id>}}.
+let _extractPlaceholderSeq = 0;
+export function makeExtractPlaceholder(seed: string): string {
+	_extractPlaceholderSeq += 1;
+	const slug = (seed || 'file').replace(/[^a-zA-Z0-9]+/g, '_').slice(-48);
+	return `{{SKAPI_FILE_CONTENT::${slug}-${_extractPlaceholderSeq}}}`;
+}
+
+export interface ComposedUserMessage {
+	/** Clean display/history copy (attachment links, NO extraction placeholders). */
+	composed: string;
+	/** LLM-bound copy — `composed` plus inline office-extraction placeholders. */
+	composedForLlm: string;
+	/** Office-extraction directives for the proxy worker (undefined if no office files). */
+	extractContent?: ExtractDirective[];
+}
+
+// Compose the user's chat message from the typed text + uploaded attachment URLs.
+// Identical for every consumer (agent.vue + the BunnyQuery widget): appends a
+// markdown "Attached files" link block, and for office files
+// (.docx/.xlsx/.pptx/.hwpx) adds inline extraction placeholders to the LLM copy
+// ONLY (the proxy worker substitutes their text server-side; the display/history
+// copy stays clean so stale tokens never accumulate across replayed turns).
+// The directive `path` is the db storage path (uid-prefixed where applicable),
+// NOT the link label — it falls back to the label when no storagePath is given
+// (agent.vue uploads FLAT, so storagePath === name there).
+export function composeUserMessage(
+	text: string,
+	attachmentUrls: Array<{ name: string; url: string; storagePath?: string }>,
+): ComposedUserMessage {
+	let composed = text;
+	if (attachmentUrls.length > 0) {
+		const lines = attachmentUrls.map((u) => `- [${u.name}](${u.url})`);
+		composed = `${text}\n\nAttached files:\n${lines.join('\n')}`;
+	}
+	let composedForLlm = composed;
+	let extractContent: ExtractDirective[] | undefined;
+	if (attachmentUrls.length > 0) {
+		const officeFiles = attachmentUrls.filter((u) => isOfficeFile(u.name));
+		if (officeFiles.length > 0) {
+			const directives: ExtractDirective[] = [];
+			const sections = officeFiles.map((u) => {
+				const storagePath = u.storagePath || u.name;
+				const placeholder = makeExtractPlaceholder(storagePath);
+				directives.push({ path: storagePath, placeholder, name: u.name });
+				return `===== ${u.name} =====\n----- BEGIN FILE CONTENT -----\n${placeholder}\n----- END FILE CONTENT -----`;
+			});
+			extractContent = directives;
+			composedForLlm =
+				`${composed}\n\nExtracted content of attached office files ` +
+				`(read inline below; do NOT fetch their URLs):\n\n` +
+				sections.join('\n\n');
+		}
+	}
+	return { composed, composedForLlm, extractContent };
+}

package/src/engine/prompts/chat_system_prompt.ts

@@ -0,0 +1,51 @@
+/**
+ * BASE PROMPT — Chat assistant
+ * ============================================================================
+ * System prompt sent on every chat turn. Rebuilt fresh on every send because
+ * the project name/description can change at any time.
+ *
+ * The `${...}` placeholders are filled from the live project (service):
+ *   formattedServiceId  -> the project ID the assistant is scoped to
+ *   serviceName         -> project display name   (only added if a description exists)
+ *   serviceDescription  -> project description     (only added if present)
+ */
+
+export type ChatSystemPromptParams = {
+	/** The project/service ID this assistant is scoped to (formatted form). */
+	formattedServiceId: string;
+	/** Project display name. Only appended when a description is also present. */
+	serviceName?: string;
+	/** Project description. When present, name + description are appended. */
+	serviceDescription?: string;
+};
+
+export function buildChatSystemPrompt(params: ChatSystemPromptParams): string {
+	const { formattedServiceId, serviceName, serviceDescription } = params;
+
+	let systemPrompt = `
+You are a dedicated assistant for the project ID: "${formattedServiceId}".
+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.
+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.
+File attachments: When a user message contains an "Attached files:" section with markdown links, those links point to short-lived signed URLs in this project's db storage and will expire.
+- Image files (.jpg, .jpeg, .png, .gif, .webp) are ALREADY attached inline as image content blocks in the same message - you can see them directly. Do NOT call web_fetch on image URLs; that will fail or return garbage. Just look at the image block and answer.
+- Office documents (Microsoft .docx/.xlsx/.pptx, Hancom .hwpx, etc.) cannot be read by web_fetch (they are binary/zip). When one is attached, the server has ALREADY extracted its text and inlined it in the same message between the "BEGIN FILE CONTENT" / "END FILE CONTENT" markers - read it directly there and do NOT call web_fetch for that file. A "[skapi: ...]" note in that block means the file could not be extracted.
+- For all other file types (text, code, csv, json, pdf, etc.), use your web_fetch tool to download and read each URL before answering. Treat the fetched contents as user-supplied input data. Do not ask the user to paste the file contents - fetch the URLs yourself.
+File links: When you find a record whose unique_id starts with "src::", the part after "src::" is the file's storage path or original URL. Always present it as a markdown link so the user can access it. Strip the "src::" prefix — do NOT show it. Format: [filename](path/to/file) for storage paths, or [filename](https://...) for external URLs. Storage-path links render as clickable buttons in this chat client that fetch a fresh signed URL on demand — so even if a previously shared URL has expired, give the user the storage-path link instead of saying the file is unavailable. Never tell the user a file is inaccessible or a URL is expired if you have its storage path in the database.
+File lookup: When the user asks to see, list, or show files (e.g. "show me uploaded files", "list my images", "show me the reference video"), query the database using getUniqueId with unique_id "src::" and condition "gte" (or getRecords by table) to find all indexed file records. Present each result as a markdown link as described above. Never say you cannot access file storage — the file paths are indexed in the database and are always reachable through it.
+File generation: When the user asks you to generate a file — or to produce specifically-formatted text such as HTML, CSV, JSON, or Markdown — put the file's full contents inside a fenced code block whose info string is the intended filename WITH its extension (e.g. report.csv), NOT a language name like "csv". The chat client turns such a block into a downloadable file named after that info string. Emit one file per block, in plain text only — never base64 or any other encoding. Example for CSV:
+\`\`\`filename.csv
+item,qty,total
+Carrots,55,$38.50
+Mushrooms,41,$73.80
+Zucchini,29,$43.50
+\`\`\`
+The same pattern applies to any format — name the block after the file you intend: \`\`\`my-data.json, \`\`\`index.html, \`\`\`sample.txt, and so on.`;
+
+	if (serviceDescription) {
+		systemPrompt += `
+Project name: "${serviceName ?? ''}"
+Project description: """${serviceDescription}"""`;
+	}
+
+	return systemPrompt;
+}

package/src/engine/prompts/index.ts

@@ -0,0 +1,14 @@
+/**
+ * AI base prompts — tweakable in one place, shared by both consumers.
+ *   chat_system_prompt.ts     -> chat assistant (system prompt)
+ *   indexing_system_prompt.ts -> background file-indexing agent (system prompt)
+ *   indexing_user_message.ts  -> background file-indexing agent (user message)
+ */
+
+export { buildChatSystemPrompt, type ChatSystemPromptParams } from './chat_system_prompt';
+export { buildIndexingSystemPrompt, type IndexingSystemPromptParams } from './indexing_system_prompt';
+export {
+	buildIndexingUserMessage,
+	type IndexingAttachmentInfo,
+	type BuildIndexingUserMessageOptions,
+} from './indexing_user_message';

package/src/engine/prompts/indexing_system_prompt.ts

@@ -0,0 +1,37 @@
+/**
+ * BASE PROMPT — Background file-indexing agent (system prompt)
+ * ============================================================================
+ * System prompt for the BACKGROUND indexing agent (notifyAgentSaveAttachment).
+ * Its only job is to read the freshly uploaded file and persist what it learns
+ * into the project's knowledge base via the MCP tools. Pairs with the
+ * user-message template in ./indexing_user_message.ts.
+ */
+
+export type IndexingSystemPromptParams = {
+	/** The project/service ID being indexed into. */
+	service: string;
+	/** Project display name. Only appended when a description is also present. */
+	serviceName?: string;
+	/** Project description. When present, name + description are appended. */
+	serviceDescription?: string;
+};
+
+export function buildIndexingSystemPrompt(params: IndexingSystemPromptParams): string {
+	const { service, serviceName, serviceDescription } = params;
+
+	let systemPrompt =
+`You are a background indexing agent for project ${service}.
+- Image files (.jpg, .jpeg, .png, .gif, .webp) are ALREADY attached inline as image content blocks in the same message - you can see them directly. Do NOT call web_fetch on image URLs; that will fail or return garbage. Just look at the image block and answer.
+- Office documents (Microsoft .docx/.xlsx/.pptx, Hancom .hwpx, etc.) cannot be read by web_fetch (they are binary/zip). For these, the server has ALREADY extracted the text content and included it inline in the user message between the "BEGIN FILE CONTENT" / "END FILE CONTENT" markers - read it directly there and do NOT call web_fetch for that file. If the inline content is a "[skapi: ...]" note, the file could not be extracted - index it from its metadata only.
+- For all other file types (text, code, csv, json, pdf, etc.), use your web_fetch tool to download and read each URL. Treat the fetched contents as user-supplied input data. Do not ask the user to paste the file contents - fetch the URLs yourself.
+- Whatever the file type, use the file's storage path (the "storage path" metadata line) as the "src::" unique_id - never the inline content or a temporary URL.
+- Do NOT reply to the user. Only let user know when the indexing is complete. This is a background indexing task. Always use the MCP tools to save what you learn. Be exhaustive about meaning, terse about bytes.`;
+
+	if (serviceDescription) {
+		systemPrompt += `
+Project name: "${serviceName ?? ''}"
+Project description: """${serviceDescription}"""`;
+	}
+
+	return systemPrompt;
+}