@btst/stack 2.3.0 → 2.5.0

package/src/plugins/ai-chat/api/plugin.ts

@@ -17,6 +17,11 @@ import {
 } from "../schemas";
 import type { Conversation, ConversationWithMessages, Message } from "../types";
 import { getAllConversations, getConversationById } from "./getters";
+import {
+	BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST,
+	BUILT_IN_PAGE_TOOL_SCHEMAS,
+} from "./page-tools";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Context passed to AI Chat API hooks
@@ -36,48 +41,46 @@ export interface ChatApiContext<TBody = any, TParams = any, TQuery = any> {
  */
 export interface AiChatBackendHooks {
 	// ============== Authorization Hooks ==============
-	// Return false to deny access
+	// Throw an error to deny access
 
 	/**
-	 * Called before processing a chat message. Return false to deny access.
+	 * Called before processing a chat message. Throw an error to deny access.
 	 * @param messages - Array of messages being sent
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeChat?: (
 		messages: Array<{ role: string; content: string }>,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before listing conversations. Return false to deny access.
+	 * Called before listing conversations. Throw an error to deny access.
 	 * @param context - Request context with headers, etc.
 	 */
-	onBeforeListConversations?: (
-		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	onBeforeListConversations?: (context: ChatApiContext) => Promise<void> | void;
 
 	/**
-	 * Called before getting a single conversation. Return false to deny access.
+	 * Called before getting a single conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being accessed
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeGetConversation?: (
 		conversationId: string,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before creating a conversation. Return false to deny access.
+	 * Called before creating a conversation. Throw an error to deny access.
 	 * @param data - Conversation data being created
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeCreateConversation?: (
 		data: { id?: string; title?: string },
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before updating a conversation. Return false to deny access.
+	 * Called before updating a conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being updated
 	 * @param data - Updated conversation data
 	 * @param context - Request context with headers, etc.
@@ -86,17 +89,34 @@ export interface AiChatBackendHooks {
 		conversationId: string,
 		data: { title?: string },
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before deleting a conversation. Return false to deny access.
+	 * Called before deleting a conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being deleted
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeDeleteConversation?: (
 		conversationId: string,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
+
+	/**
+	 * Called after the structural routeName/allowlist validation, with the list
+	 * of tool names that passed. Return a filtered subset to further restrict
+	 * which tools the LLM sees, or return [] to suppress all page tools.
+	 * Throw an Error to abort the entire chat request with a 403 response.
+	 * Not called when no tools passed the structural validation step.
+	 *
+	 * @param toolNames - Names that passed the routeName allowlist check
+	 * @param routeName - routeName claimed by the request (may be undefined)
+	 * @param context   - Full request context (headers, body, etc.)
+	 */
+	onBeforeToolsActivated?: (
+		toolNames: string[],
+		routeName: string | undefined,
+		context: ChatApiContext,
+	) => Promise<string[]> | string[];
 
 	// ============== Lifecycle Hooks ==============
 
@@ -232,6 +252,32 @@ export type AiChatMode = "authenticated" | "public";
 /**
  * Configuration for AI Chat backend plugin
  */
+/**
+ * Extracts only the literal (non-index-signature) keys from a type.
+ * For `Record<string, T>` this resolves to `never`, so collision checks are
+ * skipped when the tools map is typed with a broad string index.
+ */
+type KnownKeys<T> = {
+	[K in keyof T]: string extends K ? never : K;
+}[keyof T];
+
+/**
+ * Ensures `TClientTools` has no keys that are also literal keys in `TTools`.
+ * Colliding keys are mapped to `never`, which produces a compile-time error
+ * at the point of the duplicate key. When `TTools` uses a string index
+ * signature the check is skipped to avoid false positives.
+ */
+type NoKeyCollision<
+	TTools,
+	TClientTools extends Record<string, Tool>,
+> = KnownKeys<TTools> & keyof TClientTools extends never
+	? TClientTools
+	: {
+			[K in keyof TClientTools]: K extends KnownKeys<TTools>
+				? never // duplicate of a server-side tool — remove from clientToolSchemas
+				: TClientTools[K];
+		};
+
 export interface AiChatBackendConfig {
 	/**
 	 * The language model to use for chat completions.
@@ -269,6 +315,31 @@ export interface AiChatBackendConfig {
 	 */
 	tools?: Record<string, Tool>;
 
+	/**
+	 * Enable route-aware page tools.
+	 * When true, the server will include tool schemas for client-side page tools
+	 * (e.g. fillBlogForm, updatePageLayers) based on the availableTools list
+	 * sent with each request.
+	 * @default false
+	 */
+	enablePageTools?: boolean;
+
+	/**
+	 * Custom client-side tool schemas for non-BTST pages.
+	 * Merged with built-in page tool schemas (fillBlogForm, updatePageLayers).
+	 * Only included when enablePageTools is true and the tool name appears in
+	 * the availableTools list sent with the request.
+	 *
+	 * @example
+	 * clientToolSchemas: {
+	 *   addToCart: tool({
+	 *     description: "Add current product to cart",
+	 *     parameters: z.object({ quantity: z.number().int().min(1) }),
+	 *   }),
+	 * }
+	 */
+	clientToolSchemas?: Record<string, Tool>;
+
 	/**
 	 * Optional hooks for customizing plugin behavior
 	 */
@@ -282,7 +353,15 @@ export interface AiChatBackendConfig {
  *
  * @param config - Configuration including model, tools, and optional hooks
  */
-export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
+export const aiChatBackendPlugin = <
+	TTools extends Record<string, Tool> = Record<never, Tool>,
+	TClientTools extends Record<string, Tool> = Record<never, Tool>,
+>(
+	config: Omit<AiChatBackendConfig, "tools" | "clientToolSchemas"> & {
+		tools?: TTools;
+		clientToolSchemas?: NoKeyCollision<TTools, TClientTools>;
+	},
+) =>
 	defineBackendPlugin({
 		name: "ai-chat",
 		// Always include db schema - in public mode we just don't use it
@@ -350,7 +429,13 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 					body: chatRequestSchema,
 				},
 				async (ctx) => {
-					const { messages: rawMessages, conversationId } = ctx.body;
+					const {
+						messages: rawMessages,
+						conversationId,
+						pageContext,
+						availableTools,
+						routeName,
+					} = ctx.body;
 					const uiMessages = rawMessages as UIMessage[];
 
 					const context: ChatApiContext = {
@@ -366,15 +451,11 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 								role: msg.role,
 								content: getMessageTextContent(msg),
 							}));
-							const canChat = await config.hooks.onBeforeChat(
-								messagesForHook,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeChat!(messagesForHook, context),
+								ctx.error,
+								"Unauthorized: Cannot start chat",
 							);
-							if (!canChat) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot start chat",
-								});
-							}
 						}
 
 						const firstMessage = uiMessages[0];
@@ -388,22 +469,107 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 						// Convert UIMessages to CoreMessages for streamText
 						const modelMessages = convertToModelMessages(uiMessages);
 
-						// Add system prompt if configured
-						const messagesWithSystem = config.systemPrompt
+						// Build system prompt: base config + optional page context
+						const pageContextContent =
+							pageContext && pageContext.trim()
+								? `\n\nCurrent page context:\n${pageContext}`
+								: "";
+						const systemContent = config.systemPrompt
+							? `${config.systemPrompt}${pageContextContent}`
+							: pageContextContent || undefined;
+
+						const messagesWithSystem = systemContent
 							? [
-									{ role: "system" as const, content: config.systemPrompt },
+									{ role: "system" as const, content: systemContent },
 									...modelMessages,
 								]
 							: modelMessages;
 
+						// Merge page tool schemas when enablePageTools is on.
+						// Built-in schemas are only included when the request's routeName is in
+						// the tool's allowlist — this prevents a page from claiming tools that
+						// are intended for a different route (e.g. requesting updatePageLayers
+						// from a blog page). Consumer clientToolSchemas are trusted as-is.
+						const activePageTools: Record<string, Tool> =
+							config.enablePageTools &&
+							availableTools &&
+							availableTools.length > 0
+								? (() => {
+										const consumerSchemas: Record<string, Tool> =
+											(config.clientToolSchemas as Record<string, Tool>) ?? {};
+										return Object.fromEntries(
+											availableTools
+												.filter((name) => {
+													// Built-in tool: require routeName to be in its allowlist
+													if (name in BUILT_IN_PAGE_TOOL_SCHEMAS) {
+														const allowed =
+															BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST[name];
+														return (
+															allowed &&
+															routeName &&
+															allowed.includes(routeName)
+														);
+													}
+													// Consumer-defined tool: allow if schema is registered
+													return name in consumerSchemas;
+												})
+												.map((name) => {
+													const schema =
+														BUILT_IN_PAGE_TOOL_SCHEMAS[name] ??
+														consumerSchemas[name]!;
+													return [name, schema];
+												}),
+										);
+									})()
+								: {};
+
+						// Consumer hook: user-level tool authorization.
+						// Runs after the structural routeName allowlist check.
+						// A thrown Error is caught and returned as a 403 response,
+						// consistent with how onBeforeChat handles return false → 403.
+						if (
+							config.hooks?.onBeforeToolsActivated &&
+							Object.keys(activePageTools).length > 0
+						) {
+							try {
+								const allowed = await config.hooks.onBeforeToolsActivated(
+									Object.keys(activePageTools),
+									routeName,
+									context,
+								);
+								const allowedSet = new Set(allowed);
+								for (const key of Object.keys(activePageTools)) {
+									if (!allowedSet.has(key)) {
+										delete activePageTools[key];
+									}
+								}
+							} catch (hookError) {
+								throw ctx.error(403, {
+									message:
+										hookError instanceof Error
+											? hookError.message
+											: "Unauthorized: Tool activation denied",
+								});
+							}
+						}
+
+						// Page tools are layered under server-side tools so that a
+						// clientToolSchemas entry with the same name as a tool in
+						// config.tools never silently drops its `execute` function.
+						// Server-side tools always win on collision.
+						const mergedTools =
+							Object.keys(activePageTools).length > 0
+								? { ...activePageTools, ...config.tools }
+								: config.tools;
+
 						// PUBLIC MODE: Stream without persistence
 						if (isPublicMode) {
 							const result = streamText({
 								model: config.model,
 								messages: messagesWithSystem,
-								tools: config.tools,
+								tools: mergedTools,
 								// Enable multi-step tool calls if tools are configured
-								...(config.tools ? { stopWhen: stepCountIs(5) } : {}),
+								...(mergedTools ? { stopWhen: stepCountIs(5) } : {}),
 							});
 
 							return result.toUIMessageStreamResponse({
@@ -557,9 +723,9 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 						const result = streamText({
 							model: config.model,
 							messages: messagesWithSystem,
-							tools: config.tools,
+							tools: mergedTools,
 							// Enable multi-step tool calls if tools are configured
-							...(config.tools ? { stopWhen: stepCountIs(5) } : {}),
+							...(mergedTools ? { stopWhen: stepCountIs(5) } : {}),
 							onFinish: async (completion: { text: string }) => {
 								// Wrap in try-catch since this runs after the response is sent
 								// and errors would otherwise become unhandled promise rejections
@@ -677,15 +843,15 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 
 						// Authorization hook
 						if (config.hooks?.onBeforeCreateConversation) {
-							const canCreate = await config.hooks.onBeforeCreateConversation(
-								{ id, title },
-								context,
+							await runHookWithShim(
+								() =>
+									config.hooks!.onBeforeCreateConversation!(
+										{ id, title },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot create conversation",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create conversation",
-								});
-							}
 						}
 
 						const newConv = await adapter.create<Conversation>({
@@ -743,13 +909,11 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 
 						// Authorization hook
 						if (config.hooks?.onBeforeListConversations) {
-							const canList =
-								await config.hooks.onBeforeListConversations(context);
-							if (!canList) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot list conversations",
-								});
-							}
+							await runHookWithShim(
+								() => config.hooks!.onBeforeListConversations!(context),
+								ctx.error,
+								"Unauthorized: Cannot list conversations",
+							);
 						}
 
 						// Build where conditions - filter by userId if set
@@ -820,15 +984,11 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 
 						// Authorization hook
 						if (config.hooks?.onBeforeGetConversation) {
-							const canGet = await config.hooks.onBeforeGetConversation(
-								id,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeGetConversation!(id, context),
+								ctx.error,
+								"Unauthorized: Cannot get conversation",
 							);
-							if (!canGet) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot get conversation",
-								});
-							}
 						}
 
 						// Fetch conversation with messages in a single query using join
@@ -945,16 +1105,16 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 
 						// Authorization hook
 						if (config.hooks?.onBeforeUpdateConversation) {
-							const canUpdate = await config.hooks.onBeforeUpdateConversation(
-								id,
-								{ title },
-								context,
+							await runHookWithShim(
+								() =>
+									config.hooks!.onBeforeUpdateConversation!(
+										id,
+										{ title },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot update conversation",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update conversation",
-								});
-							}
 						}
 
 						const updated = await adapter.update<Conversation>({
@@ -1040,15 +1200,11 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 
 						// Authorization hook
 						if (config.hooks?.onBeforeDeleteConversation) {
-							const canDelete = await config.hooks.onBeforeDeleteConversation(
-								id,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeDeleteConversation!(id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete conversation",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete conversation",
-								});
-							}
 						}
 
 						// Messages are automatically deleted via cascade (onDelete: "cascade")

package/src/plugins/ai-chat/client/components/chat-input.tsx

@@ -260,14 +260,14 @@ export function ChatInput({
 				)}
 
 				{/* Text Input */}
-				<div className="relative flex-1">
+				<div className="relative flex-1 min-w-0">
 					<Textarea
 						value={input}
 						onChange={handleInputChange}
 						onKeyDown={handleKeyDown}
 						placeholder={placeholder || localization.CHAT_PLACEHOLDER}
 						className={cn(
-							"resize-none pr-12",
+							"resize-none pr-12 max-w-full",
 							isCompact
 								? "min-h-[40px] max-h-[120px] py-2"
 								: "min-h-[50px] max-h-[200px] py-3",