omnichatkit 0.0.22-b → 0.0.24-b

package/README.md

@@ -40,7 +40,7 @@ OmniChatKit is designed to be highly flexible. You can use the all-in-one `<Omni
 
 ### 1. The `<OmniChat>` Wrapper (Recommended)
 
-The `<OmniChat>` component is the easiest way to orchestrate providers, generative UI, and chat interfaces. Simply choose your `api_mode` and drop in your components.
+The `<OmniChat>` component is the easiest way to orchestrate providers, generative UI, and chat interfaces. Simply choose your `apiMode` and drop in your components.
 
 ```tsx
 import { OmniChat, SessionManager } from 'omnichatkit';
@@ -48,9 +48,8 @@ import { OmniChat, SessionManager } from 'omnichatkit';
 export default function ChatPage() {
   return (
     <OmniChat 
-      api_mode="ag-ui" // "ag-ui" or "classic"
+      apiMode="ag-ui" // "ag-ui" or "classic"
       apiEndpoint="/api/agent"
-      useA2UI={true}
       a2uiProps={{
         a2uiToolName: "render-dynamic-ui",
         agentId: "orchestratr_agent",
@@ -97,9 +96,9 @@ export default function ChatPage() {
 
 ### 3. API Route Setup
 
-Depending on your `api_mode`, you need to set up your backend endpoint.
+Depending on your `apiMode`, you need to set up your backend endpoint.
 
-#### Vercel AI SDK Route (`api_mode="classic"`)
+#### Vercel AI SDK Route (`apiMode="classic"`)
 ```typescript
 // app/api/chat/route.ts
 import { streamText } from 'ai';
@@ -115,7 +114,7 @@ export async function POST(req: Request) {
 }
 ```
 
-#### AG-UI Protocol Route (`api_mode="ag-ui"`)
+#### AG-UI Protocol Route (`apiMode="ag-ui"`)
 ```typescript
 // app/api/agent/route.ts
 import { AGUIServer } from '@ag-ui/server';
@@ -131,11 +130,11 @@ export async function POST(req: Request) {
 
 ### 4. `chatApiSchema` — Custom Backend Mapping (`classic` mode)
 
-When `api_mode="classic"`, OmniChatKit uses the Vercel AI SDK's `useChat` hook under the hood, which sends messages in its own standard body shape. If your backend API expects a **different request/response format**, pass a `chatApiSchema` prop to `<OmniChat>` to act as a transparent mapper between the two.
+When `apiMode="classic"`, OmniChatKit uses the Vercel AI SDK's `useChat` hook under the hood, which sends messages in its own standard body shape. If your backend API expects a **different request/response format**, pass a `chatApiSchema` prop to `<OmniChat>` to act as a transparent mapper between the two.
 
 ```tsx
 <OmniChat
-  api_mode="classic"
+  apiMode="classic"
   apiEndpoint="/api/my-custom-agent"
   chatApiSchema={{
     apiRequestSchema: { /* how to serialize the outbound request */ },
@@ -147,7 +146,7 @@ When `api_mode="classic"`, OmniChatKit uses the Vercel AI SDK's `useChat` hook u
 ```
 
 > [!NOTE]
-> `chatApiSchema` is a **compile-time narrowed prop** — TypeScript will reject it (type error) if you pass it while `api_mode="ag-ui"`.
+> `chatApiSchema` is a **compile-time narrowed prop** — TypeScript will reject it (type error) if you pass it while `apiMode="ag-ui"`.
 
 #### `apiRequestSchema`
 
@@ -250,7 +249,7 @@ The `ChatManager` component comes with extensive styling and layout capabilities
 - **`display`** (`"floating" | "embedded"`): Controls the layout mode of the chat manager. 
 - **`displayOptions`** (`object`): Configuration for the selected display mode.
   - `collapsible` (`boolean`): When display is "embedded", renders the component as a floating drawer (`<Sheet>`) with a dynamic toggle button.
-  - `isResizable` (`boolean`): When display is "embedded", allows the chat drawer to be resized by the user.
+  - `resizable` (`object`): Enables a drag-to-resize handle for embedded panels without needing an external wrapper. Provide sizing bounds via `{ defaultSize: number, minSize?: number, maxSize?: number }`.
 - **`position`** (`"left" | "right" | "top" | "bottom"`): Controls where the drawer docks and automatically aligns the close button correctly.
 - **`welcomeScreen`** (`boolean | ReactNode`): Set to `true` (default) to show the default welcome screen, or pass a custom React element.
 - **`maxInputCharacter`** (`number`): Optional limit for the maximum number of characters allowed in the chat input box.
@@ -377,7 +376,7 @@ The `SessionManager` handles chat history.
 Enable sessions on `OmniChat` (or either chat provider) before rendering it. Session handling is disabled by default, so chats have no session creation, persistence, or rename requests unless you opt in.
 
 ```tsx
-<OmniChat api_mode="ag-ui" sessionStorageMode="api">
+<OmniChat apiMode="ag-ui" sessionStorageMode="api">
   <SessionManager />
   <ChatManager />
 </OmniChat>
@@ -385,8 +384,14 @@ Enable sessions on `OmniChat` (or either chat provider) before rendering it. Ses
 
 #### Props
 - **`sessionStorageMode`** (`"disabled" | "api" | "memory"`): Set on `OmniChat` or a chat provider. `"disabled"` is the default; `SessionManager` throws if it is rendered in this mode.
-- **`collapsible`** (`boolean`): Enables the drawer view for space-saving layouts.
-- **`position`** (`"left" | "right"`): Where the manager should dock.
+- **`collapsible`** (`boolean`): If true, allows the session manager to be collapsed.
+- **`variant`** (`"sheet" | "inline-sheet" | "drawer" | "inline-drawer"`): Controls the visual style and collapse behavior. Defaults to `"inline-sheet"`.
+  - `"sheet"`: A slide-out panel that overlays the content.
+  - `"drawer"`: A swipeable slide-out panel that overlays the content.
+  - `"inline-sheet"`: A collapsible sidebar with Sheet styling that stays in the page flow.
+  - `"inline-drawer"`: A collapsible sidebar with Drawer styling (rounded floating design) that stays in the page flow.
+  - *Note: If `collapsible` is `false`, only inline variants (`"inline-sheet"` or `"inline-drawer"`) are allowed.*
+- **`position`** (`"left" | "right" | "top" | "bottom"`): Where the manager should dock.
 
 #### Session list style slots
 
@@ -432,7 +437,7 @@ function MyCustomChatUI() {
 
 **Resolution logic:**
 1. **Only one provider in the tree** → returns that context directly. No store lookup needed.
-2. **Both providers present** → uses the `api_mode` registered by `<OmniChat>` as a tiebreaker.
+2. **Both providers present** → uses the `apiMode` registered by `<OmniChat>` as a tiebreaker.
 3. **Neither present** → throws a descriptive error.
 
 > [!NOTE]
@@ -480,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
@@ -510,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`