omnichatkit 0.0.23-b → 0.0.24-b

package/README.md

@@ -485,6 +485,37 @@ This proxy ensures unauthorized requests are immediately dropped (returning `401
 ### 9. Working with AI Reasoning (e.g. DeepSeek `<think>`)
 OmniChatKit automatically parses and extracts `<think>` tags from incoming model streams. It strips these out of the primary text response and renders them natively as a beautiful, collapsible "Reasoning" accordion inside the message block! No extra configuration is required.
 
+### 10. Frontend Action Tooling (AG-UI)
+
+OmniChatKit provides a powerful way to define frontend tools that the AI agent can call using the `useAGUIAction` hook. This allows you to integrate application-specific behaviors like UI actions, user confirmations, or data fetching seamlessly into the agent's workflow.
+
+```tsx
+import { useAGUIAction } from "omnichatkit";
+
+function MyInteractiveComponent() {
+  useAGUIAction({
+    name: "confirmAction",
+    description: "Ask the user to confirm a specific action before proceeding",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", description: "The action that needs user confirmation" }
+      },
+      required: ["action"],
+    },
+    handler: async ({ action }) => {
+      // Execute your frontend logic, like showing a confirmation dialog
+      const confirmed = window.confirm(`Proceed with: ${action}?`);
+      return confirmed ? "approved" : "rejected";
+    },
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+Registered tools are automatically injected into the `RunAgentInput.tools` payload during the AG-UI agent turn, and the chat hook natively awaits the `handler` execution and appends the result to the conversation automatically.
+
 ---
 
 ## Core Architecture
@@ -515,10 +546,11 @@ OmniChatKit exports all necessary hooks, components, and types to give you full
 
 **Hooks**
 - `useAIChatStore`
-- `useChatContext` — auto-selects the correct context based on the active provider
-- `useAIChatContext` — explicit classic (Vercel AI SDK) context accessor
-- `useAGUIChatContext` — explicit AG-UI context accessor
+- `useChatContext` — auto-selects the correct context based on the active provider
+- `useAIChatContext` — explicit classic (Vercel AI SDK) context accessor
+- `useAGUIChatContext` — explicit AG-UI context accessor
 - `useAGUIChat`
+- `useAGUIAction`
 - `useHITL`
 - `useInterrupts`
 

package/dist/index.cjs

@@ -151,6 +151,16 @@ const useAIChatStore = (0, zustand.create)()((0, zustand_middleware.persist)((se
 	setPendingHITLAction: (action) => set({ pendingHITLAction: action }),
 	resumeExecution: () => {},
 	setResumeExecution: (fn) => set({ resumeExecution: fn }),
+	actions: {},
+	registerAction: (action) => set((state) => ({ actions: {
+		...state.actions,
+		[action.name]: action
+	} })),
+	unregisterAction: (name) => set((state) => {
+		const newActions = { ...state.actions };
+		delete newActions[name];
+		return { actions: newActions };
+	}),
 	sessions: [],
 	activeSessionId: null,
 	setSessions: (sessions) => {
@@ -570,7 +580,7 @@ function useAIChatContext() {
 * @param config.agentId - The specific agent identifier, appended to the API route.
 * @returns An object matching the Vercel AI SDK `UseChatHelpers` interface, plus custom event data.
 */
-function useAGUIChat({ api, body, agentId }) {
+function useAGUIChat({ api, body, agentId, agentDescription }) {
 	const [messages, setMessages] = (0, react.useState)([]);
 	const [input, setInput] = (0, react.useState)("");
 	const [status, setStatus] = (0, react.useState)("idle");
@@ -591,12 +601,17 @@ function useAGUIChat({ api, body, agentId }) {
 		return new _ag_ui_client.HttpAgent({
 			url: finalApiUrl,
 			threadId: currentSessionId,
+			description: agentDescription,
 			fetch: (fetchUrl, init) => fetch(fetchUrl, {
 				...init,
 				signal: abortControllerRef.current?.signal || init?.signal
 			})
 		});
-	}, [agentId, api]);
+	}, [
+		agentId,
+		api,
+		agentDescription
+	]);
 	(0, react.useEffect)(() => {
 		const currentSessionId = body?.sessionId;
 		agentRef.current = createAgent(currentSessionId);
@@ -641,12 +656,17 @@ function useAGUIChat({ api, body, agentId }) {
 		setStatus("submitted");
 		setError(void 0);
 		setEvents([]);
-		try {
-			const aguiMessages = messagesRef.current.map((m) => ({ ...m }));
+		const runAgentTurn = async (currentMessages) => {
 			setStatus("streaming");
-			agentRef.current.setMessages(aguiMessages);
+			agentRef.current.setMessages(currentMessages);
 			abortControllerRef.current = new AbortController();
-			await agentRef.current.runAgent({}, {
+			const actions = useAIChatStore.getState().actions || {};
+			const tools = Object.values(actions).map((a) => ({
+				name: a.name,
+				description: a.description,
+				parameters: a.parameters
+			}));
+			await agentRef.current.runAgent({ tools: tools.length > 0 ? tools : void 0 }, {
 				onEvent: (params) => {
 					setEvents((prev) => [...prev, params.event]);
 				},
@@ -701,8 +721,44 @@ function useAGUIChat({ api, body, agentId }) {
 					}
 				}
 			});
+			const newMessages = messagesRef.current;
+			const latestMessage = newMessages[newMessages.length - 1];
+			if (latestMessage && latestMessage.toolInvocations && latestMessage.toolInvocations.length > 0) {
+				let hasToolResult = false;
+				const newToolResults = [];
+				for (const invocation of latestMessage.toolInvocations) {
+					const action = actions[invocation.toolName];
+					if (action && action.handler) try {
+						const res = await action.handler(invocation.args);
+						newToolResults.push({
+							id: Date.now().toString() + Math.random().toString().slice(2, 6),
+							role: "tool",
+							content: typeof res === "string" ? res : JSON.stringify(res),
+							toolCallId: invocation.toolCallId
+						});
+						hasToolResult = true;
+					} catch (err) {
+						newToolResults.push({
+							id: Date.now().toString() + Math.random().toString().slice(2, 6),
+							role: "tool",
+							content: String(err),
+							error: String(err),
+							toolCallId: invocation.toolCallId
+						});
+						hasToolResult = true;
+					}
+				}
+				if (hasToolResult) {
+					messagesRef.current = [...messagesRef.current, ...newToolResults];
+					setMessages(messagesRef.current);
+					return await runAgentTurn(messagesRef.current);
+				}
+			}
 			setStatus("ready");
 			return lastAssistantResponseRef.current;
+		};
+		try {
+			return await runAgentTurn(messagesRef.current);
 		} catch (err) {
 			if (String(err).toLowerCase().includes("aborted") || err instanceof Error && err.name === "AbortError") setMessages((prev) => {
 				const lastMsg = prev[prev.length - 1];
@@ -770,7 +826,7 @@ const AGUIChatContext = (0, react.createContext)(null);
 * @param props - Provider configuration.
 * @returns A context provider wrapping the chat UI components.
 */
-function AGUIChatProvider({ children, theme = "standard", apiEndpoint = "/api/agent", agentId, sessionId, sessionStorageMode = "disabled", sessionRoute = "/session" }) {
+function AGUIChatProvider({ children, theme = "standard", apiEndpoint = "/api/agent", agentId, agentDescription, sessionId, sessionStorageMode = "disabled", sessionRoute = "/session" }) {
 	const setTheme = useAIChatStore((state) => state.setTheme);
 	const setSessionStorageMode = useAIChatStore((state) => state.setSessionStorageMode);
 	const setSessionRoute = useAIChatStore((state) => state.setSessionRoute);
@@ -801,12 +857,14 @@ function AGUIChatProvider({ children, theme = "standard", apiEndpoint = "/api/ag
 	const chatHelpers = useAGUIChat({
 		api: apiEndpoint,
 		body: sessionsEnabled ? activeSessionId ? { sessionId: activeSessionId } : sessionId ? { sessionId } : void 0 : void 0,
-		agentId
+		agentId,
+		agentDescription
 	});
 	const autoTitledSessionIdsRef = react.default.useRef(/* @__PURE__ */ new Set());
 	const titleChatHelpers = useAGUIChat({
 		api: apiEndpoint,
-		agentId
+		agentId,
+		agentDescription
 	});
 	const generateInitialSessionTitle = react.default.useCallback(async (messages) => {
 		if (!sessionsEnabled) throw new Error("Session titles require sessionStorageMode to be \"memory\" or \"api\".");
@@ -901,6 +959,32 @@ function useAGUIChatContext() {
 	return context;
 }
 //#endregion
+//#region src/hooks/useAGUIAction.ts
+/**
+* Registers an AG-UI action (tool) to be made available to the agent backend.
+* The action is passed into the RunAgentInput.tools array when useAGUIChat runs.
+* When the backend requests this tool, its handler will be executed.
+* 
+* @param action - The action definition including name, description, parameters schema and a handler.
+*/
+function useAGUIAction(action) {
+	const registerAction = useAIChatStore((state) => state.registerAction);
+	const unregisterAction = useAIChatStore((state) => state.unregisterAction);
+	(0, react.useEffect)(() => {
+		registerAction(action);
+		return () => {
+			unregisterAction(action.name);
+		};
+	}, [
+		action.name,
+		action.description,
+		action.handler,
+		action.parameters,
+		registerAction,
+		unregisterAction
+	]);
+}
+//#endregion
 //#region src/hooks/useChatContext.ts
 /**
 * `useChatContext` is a convenience hook that automatically returns the correct
@@ -5205,7 +5289,7 @@ function ChatManager({ theme, className, style, chatManagerComponentStyles = {},
 									className: "flex gap-2 w-full items-end relative",
 									children: [
 										inputTypeList && inputTypeList.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-											className: "relative shrink-0 flex items-center justify-center h-full mb-1",
+											className: "relative z-50 shrink-0 flex items-center justify-center mb-1",
 											ref: attachMenuRef,
 											children: [
 												/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -5219,7 +5303,7 @@ function ChatManager({ theme, className, style, chatManagerComponentStyles = {},
 													type: "button",
 													variant: "outline",
 													size: "icon",
-													className: (0, cn.cn)("rounded-full w-10 h-10 border-dashed", typeof inputSectionStyle.attachmentMenuStyles?.plusButtonContainerStyles === "string" ? inputSectionStyle.attachmentMenuStyles.plusButtonContainerStyles : ""),
+													className: (0, cn.cn)("rounded-full w-10 h-10 border-dashed relative z-50 bg-background", typeof inputSectionStyle.attachmentMenuStyles?.plusButtonContainerStyles === "string" ? inputSectionStyle.attachmentMenuStyles.plusButtonContainerStyles : ""),
 													style: typeof inputSectionStyle.attachmentMenuStyles?.plusButtonContainerStyles === "object" ? inputSectionStyle.attachmentMenuStyles.plusButtonContainerStyles : void 0,
 													onClick: () => setIsAttachMenuOpen(!isAttachMenuOpen),
 													children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -5231,67 +5315,62 @@ function ChatManager({ theme, className, style, chatManagerComponentStyles = {},
 														})
 													})
 												}),
-												isAttachMenuOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-													className: (0, cn.cn)("absolute bottom-[calc(100%+0.5rem)] left-0 bg-background/80 backdrop-blur-md border border-border/50 shadow-lg rounded-xl p-1 z-50 flex flex-col min-w-[120px] animate-in fade-in zoom-in duration-200 origin-bottom-left", typeof inputSectionStyle.attachmentMenuStyles?.menuContainerStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuContainerStyles : ""),
-													style: typeof inputSectionStyle.attachmentMenuStyles?.menuContainerStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuContainerStyles : void 0,
+												/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+													className: "absolute inset-0 flex items-center justify-center pointer-events-none z-40",
 													children: [
-														inputTypeList.includes("image") && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
-															type: "button",
-															className: (0, cn.cn)("flex items-center gap-2.5 px-2.5 py-2 text-xs hover:bg-accent hover:text-accent-foreground rounded-lg text-left transition-colors text-foreground font-medium", typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : ""),
-															style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : void 0,
-															onClick: () => triggerFileInput("image/*"),
-															children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-																className: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : "",
-																style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : void 0,
-																children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Image, {
-																	size: 14,
-																	className: "text-zinc-500"
-																})
-															}), "Image"]
-														}),
-														inputTypeList.includes("document") && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
-															type: "button",
-															className: (0, cn.cn)("flex items-center gap-2.5 px-2.5 py-2 text-xs hover:bg-accent hover:text-accent-foreground rounded-lg text-left transition-colors text-foreground font-medium", typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : ""),
-															style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : void 0,
-															onClick: () => triggerFileInput(".pdf,.doc,.docx,.txt,application/pdf,text/plain"),
-															children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-																className: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : "",
-																style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : void 0,
-																children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.FileText, {
-																	size: 14,
-																	className: "text-zinc-500"
-																})
-															}), "Document"]
-														}),
-														inputTypeList.includes("audio") && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
-															type: "button",
-															className: (0, cn.cn)("flex items-center gap-2.5 px-2.5 py-2 text-xs hover:bg-accent hover:text-accent-foreground rounded-lg text-left transition-colors text-foreground font-medium", typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : ""),
-															style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : void 0,
-															onClick: () => triggerFileInput("audio/*"),
-															children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-																className: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : "",
-																style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : void 0,
-																children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Mic, {
-																	size: 14,
-																	className: "text-zinc-500"
-																})
-															}), "Audio"]
-														}),
-														inputTypeList.includes("video") && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+														{
+															type: "image",
+															icon: lucide_react.Image,
+															label: "Image",
+															accept: "image/*"
+														},
+														{
+															type: "document",
+															icon: lucide_react.FileText,
+															label: "Document",
+															accept: ".pdf,.doc,.docx,.txt,application/pdf,text/plain"
+														},
+														{
+															type: "audio",
+															icon: lucide_react.Mic,
+															label: "Audio",
+															accept: "audio/*"
+														},
+														{
+															type: "video",
+															icon: lucide_react.Video,
+															label: "Video",
+															accept: "video/*"
+														}
+													].filter((item) => inputTypeList.includes(item.type)).map((item, idx, arr) => {
+														const isOpen = isAttachMenuOpen;
+														const rad = ((arr.length === 1 ? 45 : 0 + 85 / (arr.length - 1) * idx) - 90) * (Math.PI / 180);
+														const radius = 90;
+														const x = isOpen ? Math.cos(rad) * radius : 0;
+														const y = isOpen ? Math.sin(rad) * radius : 0;
+														return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 															type: "button",
-															className: (0, cn.cn)("flex items-center gap-2.5 px-2.5 py-2 text-xs hover:bg-accent hover:text-accent-foreground rounded-lg text-left transition-colors text-foreground font-medium", typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : ""),
-															style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : void 0,
-															onClick: () => triggerFileInput("video/*"),
-															children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+															title: item.label,
+															onClick: () => {
+																triggerFileInput(item.accept);
+																setIsAttachMenuOpen(false);
+															},
+															className: (0, cn.cn)("absolute top-0 left-0 w-10 h-10 rounded-full bg-background border border-border shadow-md flex items-center justify-center text-foreground hover:bg-accent transition-all duration-300 pointer-events-auto", isOpen ? "opacity-100" : "opacity-0 pointer-events-none", typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : ""),
+															style: {
+																transform: `translate(${x}px, ${y}px) scale(${isOpen ? 1 : .5})`,
+																transitionDelay: isOpen ? `${idx * 40}ms` : "0ms",
+																...typeof inputSectionStyle.attachmentMenuStyles?.menuItemStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemStyles : void 0
+															},
+															children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 																className: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "string" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : "",
 																style: typeof inputSectionStyle.attachmentMenuStyles?.menuItemIconStyles === "object" ? inputSectionStyle.attachmentMenuStyles.menuItemIconStyles : void 0,
-																children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Video, {
-																	size: 14,
+																children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(item.icon, {
+																	size: 16,
 																	className: "text-zinc-500"
 																})
-															}), "Video"]
-														})
-													]
+															})
+														}, item.type);
+													})
 												})
 											]
 										}),
@@ -6366,12 +6445,14 @@ function OmniChat({ apiMode, theme, a2uiProps, apiEndpoint, chatApiSchema, chatM
 	a2uiProps?.a2uiRenderingOption;
 	const Provider = apiMode === "ag-ui" ? AGUIChatProvider : AIChatProvider;
 	const agentId = chatManagerProps?.agentId;
+	const agentDescription = chatManagerProps?.agentDescription;
 	const sessionId = chatManagerProps?.sessionId;
 	const normalizedSessionRoute = sessionRoute.startsWith("/") ? sessionRoute : `/${sessionRoute}`;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Provider, {
 		theme,
 		apiEndpoint,
 		agentId,
+		agentDescription,
 		sessionId,
 		sessionStorageMode,
 		sessionRoute: normalizedSessionRoute,
@@ -6551,6 +6632,7 @@ exports.catalog = catalog;
 exports.catalogSchema = catalogSchema;
 exports.definitions = definitions;
 exports.surfaceBus = surfaceBus;
+exports.useAGUIAction = useAGUIAction;
 exports.useAGUIChat = useAGUIChat;
 exports.useAGUIChatContext = useAGUIChatContext;
 exports.useAIChatContext = useAIChatContext;