@super_studio/ecforce-ai-agent-react 1.1.2 → 1.2.0-canary.1

package/README.md

@@ -220,6 +220,100 @@ sendAppMessage({
 
 これにより、AI Agent 側で現在の画面や対象データに応じた応答をしやすくなります。
 
+### 3-5. `useClientTool()` でクライアントツールを登録する
+
+ブラウザ上で実行したい処理を AI Agent から呼ばせたい場合は、`useClientTool()` を使います。
+
+典型的には、以下のような用途で使います。
+
+- 現在開いている画面の React state を参照して結果を返す
+- ユーザー確認付きでクライアント側の state を更新する
+- クライアント側の UI 操作をトリガーする
+
+`useClientTool()` は `ChatbotProvider` 配下で呼び出してください。引数定義には `zod` を使います。
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { z } from "zod";
+import { useClientTool } from "@super_studio/ecforce-ai-agent-react";
+
+export function CartToolRegistration() {
+  const [selectedSku, setSelectedSku] = useState("sku_001");
+  const [isPinned, setIsPinned] = useState(false);
+
+  useClientTool({
+    name: "checkSelectedSku",
+    displayName: "選択中SKU確認",
+    description: "現在画面で選択中の商品 SKU を返します。",
+    summary: "選択中の SKU を返します。",
+    parameters: z.object({}),
+    execute: () => {
+      return {
+        selectedSku,
+        isPinned,
+      };
+    },
+  });
+
+  useClientTool({
+    name: "togglePinnedState",
+    displayName: "ピン留め切り替え",
+    description: "現在の商品をピン留めするかどうかを切り替えます。",
+    summary: "ピン留め状態を更新します。",
+    requireConfirmation: true,
+    parameters: z.object({
+      pinned: z.boolean().describe("更新後のピン留め状態"),
+    }),
+    execute: ({ pinned }) => {
+      setIsPinned(pinned);
+
+      return {
+        selectedSku,
+        isPinned: pinned,
+      };
+    },
+  });
+
+  return (
+    <div>
+      <p>selectedSku: {selectedSku}</p>
+      <p>isPinned: {String(isPinned)}</p>
+      <button onClick={() => setSelectedSku("sku_002")}>SKU を切り替える</button>
+    </div>
+  );
+}
+```
+
+#### `useClientTool()` の options
+
+```ts
+type UseClientToolOptions<TParameters extends z.ZodTypeAny> = {
+  name: string;
+  displayName: string;
+  description: string;
+  summary?: string;
+  requireConfirmation?: boolean;
+  parameters: TParameters;
+  execute: (args: z.output<TParameters>) => Promise<unknown> | unknown;
+};
+```
+
+- `name`: ツール識別子です。内部では自動で `page_` プレフィックスが付きます
+- `displayName`: UI 上で表示するツール名です
+- `description`: AI Agent が参照する詳細説明です。何をするツールか、どんな引数を受けるかを明確に書いてください
+- `summary`: ユーザー向けの短い要約です
+- `requireConfirmation`: `true` の場合、実行前にユーザー確認を要求します
+- `parameters`: ツール引数を表す `zod` スキーマです
+- `execute`: 検証済み引数を受け取ってクライアント側の処理を実行する関数です
+
+#### 補足
+
+- `name` に `page_` を自分で付けても動きますが、通常は素の名前で問題ありません
+- `execute` の返り値は AI Agent に渡されるため、JSON 化しやすい値を返すのがおすすめです
+- コンポーネントがアンマウントされるとツール登録は自動で解除されます
+
 ## 4. `@super_studio/ecforce-ai-agent-server` のセットアップ
 
 ### 4-1. サーバー側で AI Agent セッションを発行する

package/dist/components/chatbot-frame.d.mts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/components/chatbot-frame.d.ts
 type ChatbotFrameProps = {
@@ -37,7 +37,7 @@ declare function ChatbotFrame({
   enabled,
   url,
   className
-}: ChatbotFrameProps): react_jsx_runtime1.JSX.Element;
+}: ChatbotFrameProps): react_jsx_runtime0.JSX.Element;
 type SessionData = {
   token: string;
   expiresAt: string;

package/dist/components/chatbot-sheet.d.mts

@@ -1,6 +1,6 @@
 import { ChatbotFrameProps } from "./chatbot-frame.mjs";
 import React from "react";
-import * as react_jsx_runtime2 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 
 //#region src/components/chatbot-sheet.d.ts
 type ChatbotSheetProps = ChatbotFrameProps & {
@@ -9,7 +9,7 @@ type ChatbotSheetProps = ChatbotFrameProps & {
 declare function ChatbotSheet({
   sheetStyle,
   ...props
-}: ChatbotSheetProps): react_jsx_runtime2.JSX.Element;
+}: ChatbotSheetProps): react_jsx_runtime1.JSX.Element;
 //#endregion
 export { ChatbotSheet };
 //# sourceMappingURL=chatbot-sheet.d.mts.map

package/dist/components/provider/chatbot-provider.d.mts

@@ -1,3 +1,4 @@
+import { RegisteredClientTool } from "../../lib/client-tools.mjs";
 import { InitProps, MCP, SendAppMessagePayload } from "./use-chatbot-frame-handler.mjs";
 import React from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
@@ -28,6 +29,10 @@ type ChatbotContextType = {
   setSessionToken: (sessionToken: string) => void;
   /** アプリからメッセージを送信 */
   sendAppMessage: (payload: SendAppMessagePayload) => void;
+  /** Client Toolを登録 */
+  registerClientTool: (tool: RegisteredClientTool) => void;
+  /** Client Toolを解除 */
+  unregisterClientTool: (name: string) => void;
   /** チャットボットが準備できたか */
   isReady: boolean;
   /** チャットボットが初期化されたか */
@@ -38,6 +43,34 @@ type ChatbotContextType = {
    */
   setIframeEl: (iframeEl: HTMLIFrameElement | null) => void;
 };
+/**
+ * `ChatbotProvider` が提供するチャットボット状態と操作 API を取得します。
+ *
+ * @returns チャットボットの表示状態、初期化 API、Client Tool の登録 API を含むコンテキスト値。
+ *
+ * @example
+ * ```tsx
+ * import { useChatbot } from "@super_studio/ecforce-ai-agent-react";
+ *
+ * export function OpenChatButton() {
+ *   const { open, setOpen, sendAppMessage } = useChatbot();
+ *
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => {
+ *         setOpen(!open);
+ *         sendAppMessage({
+ *           message: "EC Forceの注文状況を確認したいです",
+ *         });
+ *       }}
+ *     >
+ *       Open chat
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 declare function useChatbot(): ChatbotContextType;
 type ChatbotProviderProps = {
   children: React.ReactNode;

package/dist/components/provider/chatbot-provider.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"chatbot-provider.d.mts","names":[],"sources":["../../../src/components/provider/chatbot-provider.tsx"],"sourcesContent":[],"mappings":";;;;;KAWK,kBAAA;;;EAAA;EAgBW,IAAA,EAAA,OAAA;EAEE;EAMU,OAAA,EAAA,CAAA,IAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EASF;EAAiB,UAAA,EAAA,OAAA;EAO3B;EAQX,aAAA,EAAA,CAAA,QAAoB,EAAA,OAAA,EACb,GAAA,IAAM;EAGF;EAAkB,YAAA,EAAA,OAAA;EAAY;EAAoB,eAAA,EAAA,CAAA,UAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EAAA;gBApClD;;kBAEE;;;;;;4BAMU;;;;;;;;;0BASF;;iBAOV,UAAA,CAAA,GAAU;KAQrB,oBAAA;YACO,KAAA,CAAM;;iBAGF,eAAA;;GAA8B,uBAAoB,kBAAA,CAAA,GAAA,CAAA"}
+{"version":3,"file":"chatbot-provider.d.mts","names":[],"sources":["../../../src/components/provider/chatbot-provider.tsx"],"sourcesContent":[],"mappings":";;;;;;KAYK,kBAAA;;;EAAA;EAgBW,IAAA,EAAA,OAAA;EAEE;EAMU,OAAA,EAAA,CAAA,IAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EAEC;EAWH,UAAA,EAAA,OAAA;EAAiB;EAmC3B,aAAU,EAAA,CAAA,QAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EAQrB;EAIW,YAAA,EAAA,OAAe;EAAG;EAAY,eAAA,EAAA,CAAA,UAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EAAoB;EAAA,IAAA,EAAA,CAAA,KAAA,EApElD,SAoEkD,EAAA,GAAA,IAAA;;kBAlEhD;;;;;;4BAMU;;6BAEC;;;;;;;;;;;0BAWH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmCV,UAAA,CAAA,GAAU;KAQrB,oBAAA;YACO,KAAA,CAAM;;iBAGF,eAAA;;GAA8B,uBAAoB,kBAAA,CAAA,GAAA,CAAA"}

package/dist/components/provider/chatbot-provider.mjs

@@ -7,6 +7,34 @@ import { jsx } from "react/jsx-runtime";
 
 //#region src/components/provider/chatbot-provider.tsx
 const ChatbotContext = React.createContext(void 0);
+/**
+* `ChatbotProvider` が提供するチャットボット状態と操作 API を取得します。
+*
+* @returns チャットボットの表示状態、初期化 API、Client Tool の登録 API を含むコンテキスト値。
+*
+* @example
+* ```tsx
+* import { useChatbot } from "@super_studio/ecforce-ai-agent-react";
+*
+* export function OpenChatButton() {
+*   const { open, setOpen, sendAppMessage } = useChatbot();
+*
+*   return (
+*     <button
+*       type="button"
+*       onClick={() => {
+*         setOpen(!open);
+*         sendAppMessage({
+*           message: "EC Forceの注文状況を確認したいです",
+*         });
+*       }}
+*     >
+*       Open chat
+*     </button>
+*   );
+* }
+* ```
+*/
 function useChatbot() {
 	const context = React.useContext(ChatbotContext);
 	if (!context) throw new Error("useChatbot must be used within a ChatbotProvider");
@@ -14,7 +42,7 @@ function useChatbot() {
 }
 function ChatbotProvider({ children }) {
 	const { hasOpened, open, isExpanded, isFullScreen, setOpen, setIsExpanded, setIsFullScreen } = useChatbotWindowStates();
-	const { setMcps, setAppName, setSessionToken, sendAppMessage, init, isReady, isInitialized, setIframeEl } = useChatbotFrameHandler({
+	const { setMcps, setAppName, setSessionToken, sendAppMessage, registerClientTool, unregisterClientTool, init, isReady, isInitialized, setIframeEl } = useChatbotFrameHandler({
 		setOpen,
 		setIsExpanded,
 		setIsFullScreen
@@ -29,6 +57,8 @@ function ChatbotProvider({ children }) {
 		setIsFullScreen,
 		setSessionToken,
 		sendAppMessage,
+		registerClientTool,
+		unregisterClientTool,
 		init,
 		setMcps,
 		setAppName,

package/dist/components/provider/chatbot-provider.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"chatbot-provider.mjs","names":[],"sources":["../../../src/components/provider/chatbot-provider.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport {\n  type SendAppMessagePayload,\n  useChatbotFrameHandler,\n  type InitProps,\n  type MCP,\n} from \"./use-chatbot-frame-handler\";\nimport { useChatbotWindowStates } from \"./use-chatbot-window-states\";\n\ntype ChatbotContextType = {\n  /** １回チャットボットを開いたら、固定でtrueになる */\n  hasOpened: boolean;\n  /** チャットボットを開いているか */\n  open: boolean;\n  /** チャットボットを開く */\n  setOpen: (open: boolean) => void;\n  /** チャットボットを展開しているか */\n  isExpanded: boolean;\n  /** チャットボットを展開する */\n  setIsExpanded: (expanded: boolean) => void;\n  /** チャットボットをフルスクリーンにしているか */\n  isFullScreen: boolean;\n  /** チャットボットをフルスクリーンにする */\n  setIsFullScreen: (fullScreen: boolean) => void;\n  /** チャットボットを初期化 */\n  init: (props: InitProps) => void;\n  /** MCPを設定 */\n  setMcps: (mcps: MCP[]) => void;\n  /** アプリ名を設定 */\n  setAppName: (appName: string) => void;\n  /** セッショントークンを設定 */\n  setSessionToken: (sessionToken: string) => void;\n  /** アプリからメッセージを送信 */\n  sendAppMessage: (payload: SendAppMessagePayload) => void;\n  /** チャットボットが準備できたか */\n  isReady: boolean;\n  /** チャットボットが初期化されたか */\n  isInitialized: boolean;\n  /**\n   * @internal\n   * チャットボットのiframe要素を設定\n   */\n  setIframeEl: (iframeEl: HTMLIFrameElement | null) => void;\n};\n\nconst ChatbotContext = React.createContext<ChatbotContextType | undefined>(\n  undefined,\n);\n\nexport function useChatbot() {\n  const context = React.useContext(ChatbotContext);\n  if (!context) {\n    throw new Error(\"useChatbot must be used within a ChatbotProvider\");\n  }\n  return context;\n}\n\ntype ChatbotProviderProps = {\n  children: React.ReactNode;\n};\n\nexport function ChatbotProvider({ children }: ChatbotProviderProps) {\n  const {\n    hasOpened,\n    open,\n    isExpanded,\n    isFullScreen,\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  } = useChatbotWindowStates();\n  const {\n    setMcps,\n    setAppName,\n    setSessionToken,\n    sendAppMessage,\n    init,\n    isReady,\n    isInitialized,\n    setIframeEl,\n  } = useChatbotFrameHandler({\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  });\n\n  const value = {\n    hasOpened,\n    open,\n    setOpen,\n    isExpanded,\n    setIsExpanded,\n    isFullScreen,\n    setIsFullScreen,\n    setSessionToken,\n    sendAppMessage,\n    init,\n    setMcps,\n    setAppName,\n    isReady,\n    isInitialized,\n    setIframeEl,\n  };\n\n  return (\n    <ChatbotContext.Provider value={value}>{children}</ChatbotContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;AA+CA,MAAM,iBAAiB,MAAM,cAC3B,OACD;AAED,SAAgB,aAAa;CAC3B,MAAM,UAAU,MAAM,WAAW,eAAe;AAChD,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,mDAAmD;AAErE,QAAO;;AAOT,SAAgB,gBAAgB,EAAE,YAAkC;CAClE,MAAM,EACJ,WACA,MACA,YACA,cACA,SACA,eACA,oBACE,wBAAwB;CAC5B,MAAM,EACJ,SACA,YACA,iBACA,gBACA,MACA,SACA,eACA,gBACE,uBAAuB;EACzB;EACA;EACA;EACD,CAAC;CAEF,MAAM,QAAQ;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;AAED,QACE,oBAAC,eAAe;EAAgB;EAAQ;GAAmC"}
+{"version":3,"file":"chatbot-provider.mjs","names":[],"sources":["../../../src/components/provider/chatbot-provider.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport type { RegisteredClientTool } from \"../../lib/client-tools\";\nimport {\n  useChatbotFrameHandler,\n  type InitProps,\n  type MCP,\n  type SendAppMessagePayload,\n} from \"./use-chatbot-frame-handler\";\nimport { useChatbotWindowStates } from \"./use-chatbot-window-states\";\n\ntype ChatbotContextType = {\n  /** １回チャットボットを開いたら、固定でtrueになる */\n  hasOpened: boolean;\n  /** チャットボットを開いているか */\n  open: boolean;\n  /** チャットボットを開く */\n  setOpen: (open: boolean) => void;\n  /** チャットボットを展開しているか */\n  isExpanded: boolean;\n  /** チャットボットを展開する */\n  setIsExpanded: (expanded: boolean) => void;\n  /** チャットボットをフルスクリーンにしているか */\n  isFullScreen: boolean;\n  /** チャットボットをフルスクリーンにする */\n  setIsFullScreen: (fullScreen: boolean) => void;\n  /** チャットボットを初期化 */\n  init: (props: InitProps) => void;\n  /** MCPを設定 */\n  setMcps: (mcps: MCP[]) => void;\n  /** アプリ名を設定 */\n  setAppName: (appName: string) => void;\n  /** セッショントークンを設定 */\n  setSessionToken: (sessionToken: string) => void;\n  /** アプリからメッセージを送信 */\n  sendAppMessage: (payload: SendAppMessagePayload) => void;\n  /** Client Toolを登録 */\n  registerClientTool: (tool: RegisteredClientTool) => void;\n  /** Client Toolを解除 */\n  unregisterClientTool: (name: string) => void;\n  /** チャットボットが準備できたか */\n  isReady: boolean;\n  /** チャットボットが初期化されたか */\n  isInitialized: boolean;\n  /**\n   * @internal\n   * チャットボットのiframe要素を設定\n   */\n  setIframeEl: (iframeEl: HTMLIFrameElement | null) => void;\n};\n\nconst ChatbotContext = React.createContext<ChatbotContextType | undefined>(\n  undefined,\n);\n\n/**\n * `ChatbotProvider` が提供するチャットボット状態と操作 API を取得します。\n *\n * @returns チャットボットの表示状態、初期化 API、Client Tool の登録 API を含むコンテキスト値。\n *\n * @example\n * ```tsx\n * import { useChatbot } from \"@super_studio/ecforce-ai-agent-react\";\n *\n * export function OpenChatButton() {\n *   const { open, setOpen, sendAppMessage } = useChatbot();\n *\n *   return (\n *     <button\n *       type=\"button\"\n *       onClick={() => {\n *         setOpen(!open);\n *         sendAppMessage({\n *           message: \"EC Forceの注文状況を確認したいです\",\n *         });\n *       }}\n *     >\n *       Open chat\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useChatbot() {\n  const context = React.useContext(ChatbotContext);\n  if (!context) {\n    throw new Error(\"useChatbot must be used within a ChatbotProvider\");\n  }\n  return context;\n}\n\ntype ChatbotProviderProps = {\n  children: React.ReactNode;\n};\n\nexport function ChatbotProvider({ children }: ChatbotProviderProps) {\n  const {\n    hasOpened,\n    open,\n    isExpanded,\n    isFullScreen,\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  } = useChatbotWindowStates();\n  const {\n    setMcps,\n    setAppName,\n    setSessionToken,\n    sendAppMessage,\n    registerClientTool,\n    unregisterClientTool,\n    init,\n    isReady,\n    isInitialized,\n    setIframeEl,\n  } = useChatbotFrameHandler({\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  });\n\n  const value = {\n    hasOpened,\n    open,\n    setOpen,\n    isExpanded,\n    setIsExpanded,\n    isFullScreen,\n    setIsFullScreen,\n    setSessionToken,\n    sendAppMessage,\n    registerClientTool,\n    unregisterClientTool,\n    init,\n    setMcps,\n    setAppName,\n    isReady,\n    isInitialized,\n    setIframeEl,\n  };\n\n  return (\n    <ChatbotContext.Provider value={value}>{children}</ChatbotContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;AAoDA,MAAM,iBAAiB,MAAM,cAC3B,OACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BD,SAAgB,aAAa;CAC3B,MAAM,UAAU,MAAM,WAAW,eAAe;AAChD,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,mDAAmD;AAErE,QAAO;;AAOT,SAAgB,gBAAgB,EAAE,YAAkC;CAClE,MAAM,EACJ,WACA,MACA,YACA,cACA,SACA,eACA,oBACE,wBAAwB;CAC5B,MAAM,EACJ,SACA,YACA,iBACA,gBACA,oBACA,sBACA,MACA,SACA,eACA,gBACE,uBAAuB;EACzB;EACA;EACA;EACD,CAAC;CAEF,MAAM,QAAQ;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;AAED,QACE,oBAAC,eAAe;EAAgB;EAAQ;GAAmC"}

package/dist/components/provider/use-chatbot-frame-handler.d.mts

@@ -1,3 +1,4 @@
+import "../../lib/client-tools.mjs";
 import React from "react";
 
 //#region src/components/provider/use-chatbot-frame-handler.d.ts
@@ -13,15 +14,23 @@ type InitProps = {
   sessionToken?: string;
 };
 type AppMessageAttachment = {
+  /** 添付ファイルの表示名です。 */
   fileName: string;
+  /** 添付ファイルの MIME type です。 */
   mediaType: string;
+  /** 添付ファイルを取得できる URL です。 */
   url: string;
 };
 type SendAppMessagePayload = {
+  /** チャット上に表示するタイトルです。 */
   title?: string;
+  /** ユーザーに表示するメッセージ本文です。 */
   message: string;
+  /** UI に表示せず、裏側のコンテキストとして渡すメッセージです。 */
   hiddenMessage?: string;
+  /** 新規チャットを開始してから送るかを指定します。 */
   startOnNewChat?: boolean;
+  /** メッセージと一緒に渡す添付ファイル一覧です。 */
   attachments?: AppMessageAttachment[];
 };
 //#endregion

package/dist/components/provider/use-chatbot-frame-handler.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"use-chatbot-frame-handler.d.mts","names":[],"sources":["../../../src/components/provider/use-chatbot-frame-handler.tsx"],"sourcesContent":[],"mappings":";;;;KAcY,GAAA;;;YAGA;;KAGA,SAAA;SACH;;;;KAKG,oBAAA;;;;;KAMA,qBAAA;;;;;gBAKI"}
+{"version":3,"file":"use-chatbot-frame-handler.d.mts","names":[],"sources":["../../../src/components/provider/use-chatbot-frame-handler.tsx"],"sourcesContent":[],"mappings":";;;;;KAsBY,GAAA;;;YAGA;;KAGA,SAAA;SACH;;;;KAKG,oBAAA;;;;;;;;KASA,qBAAA;;;;;;;;;;gBAUI"}

package/dist/components/provider/use-chatbot-frame-handler.mjs

@@ -4,11 +4,46 @@ import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.103.0/hel
 import React from "react";
 
 //#region src/components/provider/use-chatbot-frame-handler.tsx
+function serializeError(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return "Unknown client tool error";
+}
+/**
+* iframe と親アプリ間のメッセージ送受信を管理し、チャットボット制御 API をまとめます。
+*
+* @returns iframe 初期化、メッセージ送信、Client Tool 登録に使うハンドラ一式を返します。
+*
+* @example
+* ```tsx
+* export function FrameBridge() {
+*   const [open, setOpen] = React.useState(false);
+*   const [isExpanded, setIsExpanded] = React.useState(false);
+*   const [isFullScreen, setIsFullScreen] = React.useState(false);
+*   const { setIframeEl, init, sendAppMessage, isReady } =
+*     useChatbotFrameHandler({
+*       setOpen,
+*       setIsExpanded,
+*       setIsFullScreen,
+*     });
+*
+*   React.useEffect(() => {
+*     if (isReady) {
+*       init({ appName: "EC Force" });
+*       sendAppMessage({ message: "在庫を確認したいです" });
+*     }
+*   }, [init, isReady, sendAppMessage]);
+*
+*   return <iframe ref={setIframeEl} src="https://example.com/embed" />;
+* }
+* ```
+*/
 function useChatbotFrameHandler({ setOpen, setIsExpanded, setIsFullScreen }) {
 	const [iframeEl, setIframeEl] = React.useState(null);
 	const [isReady, setIsReady] = React.useState(false);
 	const [isInitialized, setIsInitialized] = React.useState(false);
 	const pendingAppMessageRef = React.useRef(null);
+	const clientToolRegistryRef = React.useRef(/* @__PURE__ */ new Map());
 	const postMessage = React.useCallback((message) => {
 		if (iframeEl === null || iframeEl === void 0 ? void 0 : iframeEl.contentWindow) {
 			if (process.env.NODE_ENV === "development") console.log("sending message to iframe", message);
@@ -61,6 +96,42 @@ function useChatbotFrameHandler({ setOpen, setIsExpanded, setIsFullScreen }) {
 	React.useEffect(() => {
 		flushPendingAppMessage();
 	}, [flushPendingAppMessage]);
+	const registerClientTool = React.useCallback((tool) => {
+		clientToolRegistryRef.current.set(tool.definition.name, tool);
+		if (!isReady || !isInitialized) return;
+		postMessage({
+			type: "registerClientTools",
+			tools: [tool.definition]
+		});
+	}, [
+		isInitialized,
+		isReady,
+		postMessage
+	]);
+	const unregisterClientTool = React.useCallback((name) => {
+		if (!clientToolRegistryRef.current.delete(name) || !isReady || !isInitialized) return;
+		postMessage({
+			type: "unregisterClientTools",
+			names: [name]
+		});
+	}, [
+		isInitialized,
+		isReady,
+		postMessage
+	]);
+	React.useEffect(() => {
+		if (!isReady || !isInitialized) return;
+		const tools = [...clientToolRegistryRef.current.values()].map((tool) => tool.definition);
+		if (tools.length === 0) return;
+		postMessage({
+			type: "registerClientTools",
+			tools
+		});
+	}, [
+		isInitialized,
+		isReady,
+		postMessage
+	]);
 	React.useEffect(() => {
 		const iframe = iframeEl;
 		if (!iframe) return;
@@ -93,6 +164,34 @@ function useChatbotFrameHandler({ setOpen, setIsExpanded, setIsFullScreen }) {
 				case "RELOAD_CHATBOT":
 					iframe.src = iframe.src;
 					break;
+				case "EXECUTE_CLIENT_TOOL": {
+					const { callId, name, args } = event.data;
+					const tool = clientToolRegistryRef.current.get(name);
+					if (!tool) {
+						postMessage({
+							type: "clientToolResult",
+							callId,
+							error: `Client tool not found: ${name}`
+						});
+						break;
+					}
+					(async () => {
+						try {
+							postMessage({
+								type: "clientToolResult",
+								callId,
+								result: await tool.execute(args)
+							});
+						} catch (error) {
+							postMessage({
+								type: "clientToolResult",
+								callId,
+								error: serializeError(error)
+							});
+						}
+					})();
+					break;
+				}
 			}
 		};
 		const handleIframeLoad = () => {
@@ -112,6 +211,8 @@ function useChatbotFrameHandler({ setOpen, setIsExpanded, setIsFullScreen }) {
 		setAppName,
 		setSessionToken,
 		sendAppMessage,
+		registerClientTool,
+		unregisterClientTool,
 		setIframeEl,
 		isReady,
 		isInitialized

package/dist/components/provider/use-chatbot-frame-handler.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-chatbot-frame-handler.mjs","names":[],"sources":["../../../src/components/provider/use-chatbot-frame-handler.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\n\nexport type IframeMessage =\n  | { type: \"CHATBOT_READY\" }\n  | { type: \"CHATBOT_INITIALIZED\" }\n  | { type: \"CLOSE_CHATBOT\" }\n  | { type: \"EXPAND_CHATBOT\" }\n  | { type: \"SHRINK_CHATBOT\" }\n  | { type: \"FULLSCREEN_CHATBOT\" }\n  | { type: \"EXIT_FULLSCREEN_CHATBOT\" }\n  | { type: \"RELOAD_CHATBOT\" };\n\nexport type MCP = {\n  name: string;\n  url: string;\n  headers?: Record<string, string>;\n};\n\nexport type InitProps = {\n  mcps?: MCP[];\n  appName?: string;\n  sessionToken?: string;\n};\n\nexport type AppMessageAttachment = {\n  fileName: string;\n  mediaType: string;\n  url: string;\n};\n\nexport type SendAppMessagePayload = {\n  title?: string;\n  message: string;\n  hiddenMessage?: string;\n  startOnNewChat?: boolean;\n  attachments?: AppMessageAttachment[];\n};\n\nexport type ParentMessage =\n  | {\n      type: \"mcps\";\n      mcps: MCP[];\n    }\n  | {\n      type: \"appName\";\n      appName: string;\n    }\n  | {\n      type: \"sessionToken\";\n      sessionToken: string;\n    }\n  | {\n      type: \"init\";\n      mcps?: MCP[];\n      appName?: string;\n      sessionToken?: string;\n    }\n  | {\n      type: \"appMessage\";\n      payload: SendAppMessagePayload;\n    };\n\nexport function useChatbotFrameHandler({\n  setOpen,\n  setIsExpanded,\n  setIsFullScreen,\n}: {\n  setOpen: (open: boolean) => void;\n  setIsExpanded: (expanded: boolean) => void;\n  setIsFullScreen: (fullScreen: boolean) => void;\n}) {\n  const [iframeEl, setIframeEl] = React.useState<HTMLIFrameElement | null>(\n    null,\n  );\n  const [isReady, setIsReady] = React.useState(false);\n  const [isInitialized, setIsInitialized] = React.useState(false);\n  const pendingAppMessageRef = React.useRef<SendAppMessagePayload | null>(null);\n\n  // helper to post message to the iframe\n  const postMessage = React.useCallback(\n    (message: ParentMessage) => {\n      if (iframeEl?.contentWindow) {\n        if (process.env.NODE_ENV === \"development\") {\n          console.log(\"sending message to iframe\", message);\n        }\n        iframeEl.contentWindow.postMessage(message, \"*\");\n        return true;\n      }\n      return false;\n    },\n    [iframeEl],\n  );\n\n  const init = React.useCallback(\n    (props: InitProps) => {\n      postMessage({\n        type: \"init\",\n        ...props,\n      });\n    },\n    [postMessage],\n  );\n\n  const setMcps = React.useCallback(\n    (mcps: MCP[]) => {\n      postMessage({ type: \"mcps\", mcps });\n    },\n    [postMessage],\n  );\n\n  const setAppName = React.useCallback(\n    (appName: string) => {\n      postMessage({ type: \"appName\", appName });\n    },\n    [postMessage],\n  );\n\n  const setSessionToken = React.useCallback(\n    (sessionToken: string) => {\n      postMessage({ type: \"sessionToken\", sessionToken });\n    },\n    [postMessage],\n  );\n\n  const flushPendingAppMessage = React.useCallback(() => {\n    const pendingPayload = pendingAppMessageRef.current;\n    if (!pendingPayload || !isReady || !isInitialized) {\n      return false;\n    }\n\n    const sent = postMessage({\n      type: \"appMessage\",\n      payload: pendingPayload,\n    });\n\n    if (sent) {\n      pendingAppMessageRef.current = null;\n    }\n\n    return sent;\n  }, [isInitialized, isReady, postMessage]);\n\n  const sendAppMessage = React.useCallback(\n    (payload: SendAppMessagePayload) => {\n      pendingAppMessageRef.current = {\n        ...payload,\n        startOnNewChat: payload.startOnNewChat ?? true,\n      };\n      setOpen(true);\n      flushPendingAppMessage();\n    },\n    [flushPendingAppMessage, setOpen],\n  );\n\n  React.useEffect(() => {\n    flushPendingAppMessage();\n  }, [flushPendingAppMessage]);\n\n  // Initialize and setup listeners\n  React.useEffect(() => {\n    const iframe = iframeEl;\n    if (!iframe) {\n      return;\n    }\n\n    const handleMessage = (event: MessageEvent<IframeMessage>) => {\n      if (event.source !== iframe.contentWindow) {\n        return;\n      }\n      if (process.env.NODE_ENV === \"development\") {\n        console.log(\"iframe message\", event.data);\n      }\n      // Handle iframe messages\n      switch (event.data?.type) {\n        case \"CHATBOT_READY\":\n          setIsReady(true);\n          break;\n        case \"CHATBOT_INITIALIZED\":\n          setIsInitialized(true);\n          break;\n        case \"CLOSE_CHATBOT\":\n          setOpen(false);\n          break;\n        case \"EXPAND_CHATBOT\":\n          setIsExpanded(true);\n          break;\n        case \"SHRINK_CHATBOT\":\n          setIsExpanded(false);\n          break;\n        case \"FULLSCREEN_CHATBOT\":\n          setIsFullScreen(true);\n          break;\n        case \"EXIT_FULLSCREEN_CHATBOT\":\n          setIsFullScreen(false);\n          break;\n        case \"RELOAD_CHATBOT\":\n          // reload iframe\n          iframe.src = iframe.src;\n          break;\n      }\n    };\n\n    const handleIframeLoad = () => {\n      setIsReady(false);\n      setIsInitialized(false);\n    };\n\n    window.addEventListener(\"message\", handleMessage);\n    iframe.addEventListener(\"load\", handleIframeLoad);\n\n    return () => {\n      window.removeEventListener(\"message\", handleMessage);\n      iframe.removeEventListener(\"load\", handleIframeLoad);\n    };\n  }, [iframeEl]); // Run when iframe gets mounted\n\n  return {\n    init,\n    setMcps,\n    setAppName,\n    setSessionToken,\n    sendAppMessage,\n    setIframeEl,\n    isReady,\n    isInitialized,\n  };\n}\n"],"mappings":";;;;;;AAgEA,SAAgB,uBAAuB,EACrC,SACA,eACA,mBAKC;CACD,MAAM,CAAC,UAAU,eAAe,MAAM,SACpC,KACD;CACD,MAAM,CAAC,SAAS,cAAc,MAAM,SAAS,MAAM;CACnD,MAAM,CAAC,eAAe,oBAAoB,MAAM,SAAS,MAAM;CAC/D,MAAM,uBAAuB,MAAM,OAAqC,KAAK;CAG7E,MAAM,cAAc,MAAM,aACvB,YAA2B;AAC1B,0DAAI,SAAU,eAAe;AAC3B,OAAI,QAAQ,IAAI,aAAa,cAC3B,SAAQ,IAAI,6BAA6B,QAAQ;AAEnD,YAAS,cAAc,YAAY,SAAS,IAAI;AAChD,UAAO;;AAET,SAAO;IAET,CAAC,SAAS,CACX;CAED,MAAM,OAAO,MAAM,aAChB,UAAqB;AACpB,+BACE,MAAM,UACH,OACH;IAEJ,CAAC,YAAY,CACd;CAED,MAAM,UAAU,MAAM,aACnB,SAAgB;AACf,cAAY;GAAE,MAAM;GAAQ;GAAM,CAAC;IAErC,CAAC,YAAY,CACd;CAED,MAAM,aAAa,MAAM,aACtB,YAAoB;AACnB,cAAY;GAAE,MAAM;GAAW;GAAS,CAAC;IAE3C,CAAC,YAAY,CACd;CAED,MAAM,kBAAkB,MAAM,aAC3B,iBAAyB;AACxB,cAAY;GAAE,MAAM;GAAgB;GAAc,CAAC;IAErD,CAAC,YAAY,CACd;CAED,MAAM,yBAAyB,MAAM,kBAAkB;EACrD,MAAM,iBAAiB,qBAAqB;AAC5C,MAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,cAClC,QAAO;EAGT,MAAM,OAAO,YAAY;GACvB,MAAM;GACN,SAAS;GACV,CAAC;AAEF,MAAI,KACF,sBAAqB,UAAU;AAGjC,SAAO;IACN;EAAC;EAAe;EAAS;EAAY,CAAC;CAEzC,MAAM,iBAAiB,MAAM,aAC1B,YAAmC;;AAClC,uBAAqB,4CAChB,gBACH,yCAAgB,QAAQ,uFAAkB;AAE5C,UAAQ,KAAK;AACb,0BAAwB;IAE1B,CAAC,wBAAwB,QAAQ,CAClC;AAED,OAAM,gBAAgB;AACpB,0BAAwB;IACvB,CAAC,uBAAuB,CAAC;AAG5B,OAAM,gBAAgB;EACpB,MAAM,SAAS;AACf,MAAI,CAAC,OACH;EAGF,MAAM,iBAAiB,UAAuC;;AAC5D,OAAI,MAAM,WAAW,OAAO,cAC1B;AAEF,OAAI,QAAQ,IAAI,aAAa,cAC3B,SAAQ,IAAI,kBAAkB,MAAM,KAAK;AAG3C,0BAAQ,MAAM,gEAAM,MAApB;IACE,KAAK;AACH,gBAAW,KAAK;AAChB;IACF,KAAK;AACH,sBAAiB,KAAK;AACtB;IACF,KAAK;AACH,aAAQ,MAAM;AACd;IACF,KAAK;AACH,mBAAc,KAAK;AACnB;IACF,KAAK;AACH,mBAAc,MAAM;AACpB;IACF,KAAK;AACH,qBAAgB,KAAK;AACrB;IACF,KAAK;AACH,qBAAgB,MAAM;AACtB;IACF,KAAK;AAEH,YAAO,MAAM,OAAO;AACpB;;;EAIN,MAAM,yBAAyB;AAC7B,cAAW,MAAM;AACjB,oBAAiB,MAAM;;AAGzB,SAAO,iBAAiB,WAAW,cAAc;AACjD,SAAO,iBAAiB,QAAQ,iBAAiB;AAEjD,eAAa;AACX,UAAO,oBAAoB,WAAW,cAAc;AACpD,UAAO,oBAAoB,QAAQ,iBAAiB;;IAErD,CAAC,SAAS,CAAC;AAEd,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"use-chatbot-frame-handler.mjs","names":[],"sources":["../../../src/components/provider/use-chatbot-frame-handler.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport type {\n  ClientToolDefinition,\n  ClientToolExecuteRequest,\n  RegisteredClientTool,\n} from \"../../lib/client-tools\";\n\nexport type IframeMessage =\n  | { type: \"CHATBOT_READY\" }\n  | { type: \"CHATBOT_INITIALIZED\" }\n  | { type: \"CLOSE_CHATBOT\" }\n  | { type: \"EXPAND_CHATBOT\" }\n  | { type: \"SHRINK_CHATBOT\" }\n  | { type: \"FULLSCREEN_CHATBOT\" }\n  | { type: \"EXIT_FULLSCREEN_CHATBOT\" }\n  | { type: \"RELOAD_CHATBOT\" }\n  | ({\n      type: \"EXECUTE_CLIENT_TOOL\";\n    } & ClientToolExecuteRequest);\n\nexport type MCP = {\n  name: string;\n  url: string;\n  headers?: Record<string, string>;\n};\n\nexport type InitProps = {\n  mcps?: MCP[];\n  appName?: string;\n  sessionToken?: string;\n};\n\nexport type AppMessageAttachment = {\n  /** 添付ファイルの表示名です。 */\n  fileName: string;\n  /** 添付ファイルの MIME type です。 */\n  mediaType: string;\n  /** 添付ファイルを取得できる URL です。 */\n  url: string;\n};\n\nexport type SendAppMessagePayload = {\n  /** チャット上に表示するタイトルです。 */\n  title?: string;\n  /** ユーザーに表示するメッセージ本文です。 */\n  message: string;\n  /** UI に表示せず、裏側のコンテキストとして渡すメッセージです。 */\n  hiddenMessage?: string;\n  /** 新規チャットを開始してから送るかを指定します。 */\n  startOnNewChat?: boolean;\n  /** メッセージと一緒に渡す添付ファイル一覧です。 */\n  attachments?: AppMessageAttachment[];\n};\n\nexport type ParentMessage =\n  | {\n      type: \"mcps\";\n      mcps: MCP[];\n    }\n  | {\n      type: \"appName\";\n      appName: string;\n    }\n  | {\n      type: \"sessionToken\";\n      sessionToken: string;\n    }\n  | {\n      type: \"init\";\n      mcps?: MCP[];\n      appName?: string;\n      sessionToken?: string;\n    }\n  | {\n      type: \"appMessage\";\n      payload: SendAppMessagePayload;\n    }\n  | {\n      type: \"registerClientTools\";\n      tools: ClientToolDefinition[];\n    }\n  | {\n      type: \"unregisterClientTools\";\n      names: string[];\n    }\n  | {\n      type: \"clientToolResult\";\n      callId: string;\n      result?: unknown;\n      error?: string;\n    };\n\nfunction serializeError(error: unknown) {\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  if (typeof error === \"string\") {\n    return error;\n  }\n\n  return \"Unknown client tool error\";\n}\n\ntype UseChatbotFrameHandlerProps = {\n  /** チャットボットの開閉状態を更新します。 */\n  setOpen: (open: boolean) => void;\n  /** 展開状態を更新します。 */\n  setIsExpanded: (expanded: boolean) => void;\n  /** フルスクリーン状態を更新します。 */\n  setIsFullScreen: (fullScreen: boolean) => void;\n};\n\n/**\n * iframe と親アプリ間のメッセージ送受信を管理し、チャットボット制御 API をまとめます。\n *\n * @returns iframe 初期化、メッセージ送信、Client Tool 登録に使うハンドラ一式を返します。\n *\n * @example\n * ```tsx\n * export function FrameBridge() {\n *   const [open, setOpen] = React.useState(false);\n *   const [isExpanded, setIsExpanded] = React.useState(false);\n *   const [isFullScreen, setIsFullScreen] = React.useState(false);\n *   const { setIframeEl, init, sendAppMessage, isReady } =\n *     useChatbotFrameHandler({\n *       setOpen,\n *       setIsExpanded,\n *       setIsFullScreen,\n *     });\n *\n *   React.useEffect(() => {\n *     if (isReady) {\n *       init({ appName: \"EC Force\" });\n *       sendAppMessage({ message: \"在庫を確認したいです\" });\n *     }\n *   }, [init, isReady, sendAppMessage]);\n *\n *   return <iframe ref={setIframeEl} src=\"https://example.com/embed\" />;\n * }\n * ```\n */\nexport function useChatbotFrameHandler({\n  setOpen,\n  setIsExpanded,\n  setIsFullScreen,\n}: UseChatbotFrameHandlerProps) {\n  const [iframeEl, setIframeEl] = React.useState<HTMLIFrameElement | null>(\n    null,\n  );\n  const [isReady, setIsReady] = React.useState(false);\n  const [isInitialized, setIsInitialized] = React.useState(false);\n  const pendingAppMessageRef = React.useRef<SendAppMessagePayload | null>(null);\n  const clientToolRegistryRef = React.useRef(\n    new Map<string, RegisteredClientTool>(),\n  );\n\n  // helper to post message to the iframe\n  const postMessage = React.useCallback(\n    (message: ParentMessage) => {\n      if (iframeEl?.contentWindow) {\n        if (process.env.NODE_ENV === \"development\") {\n          console.log(\"sending message to iframe\", message);\n        }\n        iframeEl.contentWindow.postMessage(message, \"*\");\n        return true;\n      }\n      return false;\n    },\n    [iframeEl],\n  );\n\n  const init = React.useCallback(\n    (props: InitProps) => {\n      postMessage({\n        type: \"init\",\n        ...props,\n      });\n    },\n    [postMessage],\n  );\n\n  const setMcps = React.useCallback(\n    (mcps: MCP[]) => {\n      postMessage({ type: \"mcps\", mcps });\n    },\n    [postMessage],\n  );\n\n  const setAppName = React.useCallback(\n    (appName: string) => {\n      postMessage({ type: \"appName\", appName });\n    },\n    [postMessage],\n  );\n\n  const setSessionToken = React.useCallback(\n    (sessionToken: string) => {\n      postMessage({ type: \"sessionToken\", sessionToken });\n    },\n    [postMessage],\n  );\n\n  const flushPendingAppMessage = React.useCallback(() => {\n    const pendingPayload = pendingAppMessageRef.current;\n    if (!pendingPayload || !isReady || !isInitialized) {\n      return false;\n    }\n\n    const sent = postMessage({\n      type: \"appMessage\",\n      payload: pendingPayload,\n    });\n\n    if (sent) {\n      pendingAppMessageRef.current = null;\n    }\n\n    return sent;\n  }, [isInitialized, isReady, postMessage]);\n\n  const sendAppMessage = React.useCallback(\n    (payload: SendAppMessagePayload) => {\n      pendingAppMessageRef.current = {\n        ...payload,\n        startOnNewChat: payload.startOnNewChat ?? true,\n      };\n      setOpen(true);\n      flushPendingAppMessage();\n    },\n    [flushPendingAppMessage, setOpen],\n  );\n\n  React.useEffect(() => {\n    flushPendingAppMessage();\n  }, [flushPendingAppMessage]);\n\n  const registerClientTool = React.useCallback(\n    (tool: RegisteredClientTool) => {\n      clientToolRegistryRef.current.set(tool.definition.name, tool);\n      if (!isReady || !isInitialized) {\n        return;\n      }\n\n      postMessage({\n        type: \"registerClientTools\",\n        tools: [tool.definition],\n      });\n    },\n    [isInitialized, isReady, postMessage],\n  );\n\n  const unregisterClientTool = React.useCallback(\n    (name: string) => {\n      const deleted = clientToolRegistryRef.current.delete(name);\n      if (!deleted || !isReady || !isInitialized) {\n        return;\n      }\n\n      postMessage({\n        type: \"unregisterClientTools\",\n        names: [name],\n      });\n    },\n    [isInitialized, isReady, postMessage],\n  );\n\n  React.useEffect(() => {\n    if (!isReady || !isInitialized) {\n      return;\n    }\n\n    const tools = [...clientToolRegistryRef.current.values()].map(\n      (tool) => tool.definition,\n    );\n    if (tools.length === 0) {\n      return;\n    }\n\n    postMessage({\n      type: \"registerClientTools\",\n      tools,\n    });\n  }, [isInitialized, isReady, postMessage]);\n\n  // Initialize and setup listeners\n  React.useEffect(() => {\n    const iframe = iframeEl;\n    if (!iframe) {\n      return;\n    }\n\n    const handleMessage = (event: MessageEvent<IframeMessage>) => {\n      if (event.source !== iframe.contentWindow) {\n        return;\n      }\n      if (process.env.NODE_ENV === \"development\") {\n        console.log(\"iframe message\", event.data);\n      }\n      // Handle iframe messages\n      switch (event.data?.type) {\n        case \"CHATBOT_READY\":\n          setIsReady(true);\n          break;\n        case \"CHATBOT_INITIALIZED\":\n          setIsInitialized(true);\n          break;\n        case \"CLOSE_CHATBOT\":\n          setOpen(false);\n          break;\n        case \"EXPAND_CHATBOT\":\n          setIsExpanded(true);\n          break;\n        case \"SHRINK_CHATBOT\":\n          setIsExpanded(false);\n          break;\n        case \"FULLSCREEN_CHATBOT\":\n          setIsFullScreen(true);\n          break;\n        case \"EXIT_FULLSCREEN_CHATBOT\":\n          setIsFullScreen(false);\n          break;\n        case \"RELOAD_CHATBOT\":\n          // reload iframe\n          iframe.src = iframe.src;\n          break;\n        case \"EXECUTE_CLIENT_TOOL\": {\n          const { callId, name, args } = event.data;\n          const tool = clientToolRegistryRef.current.get(name);\n          if (!tool) {\n            postMessage({\n              type: \"clientToolResult\",\n              callId,\n              error: `Client tool not found: ${name}`,\n            });\n            break;\n          }\n\n          void (async () => {\n            try {\n              const result = await tool.execute(args);\n              postMessage({\n                type: \"clientToolResult\",\n                callId,\n                result,\n              });\n            } catch (error) {\n              postMessage({\n                type: \"clientToolResult\",\n                callId,\n                error: serializeError(error),\n              });\n            }\n          })();\n          break;\n        }\n      }\n    };\n\n    const handleIframeLoad = () => {\n      setIsReady(false);\n      setIsInitialized(false);\n    };\n\n    window.addEventListener(\"message\", handleMessage);\n    iframe.addEventListener(\"load\", handleIframeLoad);\n\n    return () => {\n      window.removeEventListener(\"message\", handleMessage);\n      iframe.removeEventListener(\"load\", handleIframeLoad);\n    };\n  }, [iframeEl]); // Run when iframe gets mounted\n\n  return {\n    init,\n    setMcps,\n    setAppName,\n    setSessionToken,\n    sendAppMessage,\n    registerClientTool,\n    unregisterClientTool,\n    setIframeEl,\n    isReady,\n    isInitialized,\n  };\n}\n"],"mappings":";;;;;;AA8FA,SAAS,eAAe,OAAgB;AACtC,KAAI,iBAAiB,MACnB,QAAO,MAAM;AAGf,KAAI,OAAO,UAAU,SACnB,QAAO;AAGT,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCT,SAAgB,uBAAuB,EACrC,SACA,eACA,mBAC8B;CAC9B,MAAM,CAAC,UAAU,eAAe,MAAM,SACpC,KACD;CACD,MAAM,CAAC,SAAS,cAAc,MAAM,SAAS,MAAM;CACnD,MAAM,CAAC,eAAe,oBAAoB,MAAM,SAAS,MAAM;CAC/D,MAAM,uBAAuB,MAAM,OAAqC,KAAK;CAC7E,MAAM,wBAAwB,MAAM,uBAClC,IAAI,KAAmC,CACxC;CAGD,MAAM,cAAc,MAAM,aACvB,YAA2B;AAC1B,0DAAI,SAAU,eAAe;AAC3B,OAAI,QAAQ,IAAI,aAAa,cAC3B,SAAQ,IAAI,6BAA6B,QAAQ;AAEnD,YAAS,cAAc,YAAY,SAAS,IAAI;AAChD,UAAO;;AAET,SAAO;IAET,CAAC,SAAS,CACX;CAED,MAAM,OAAO,MAAM,aAChB,UAAqB;AACpB,+BACE,MAAM,UACH,OACH;IAEJ,CAAC,YAAY,CACd;CAED,MAAM,UAAU,MAAM,aACnB,SAAgB;AACf,cAAY;GAAE,MAAM;GAAQ;GAAM,CAAC;IAErC,CAAC,YAAY,CACd;CAED,MAAM,aAAa,MAAM,aACtB,YAAoB;AACnB,cAAY;GAAE,MAAM;GAAW;GAAS,CAAC;IAE3C,CAAC,YAAY,CACd;CAED,MAAM,kBAAkB,MAAM,aAC3B,iBAAyB;AACxB,cAAY;GAAE,MAAM;GAAgB;GAAc,CAAC;IAErD,CAAC,YAAY,CACd;CAED,MAAM,yBAAyB,MAAM,kBAAkB;EACrD,MAAM,iBAAiB,qBAAqB;AAC5C,MAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,cAClC,QAAO;EAGT,MAAM,OAAO,YAAY;GACvB,MAAM;GACN,SAAS;GACV,CAAC;AAEF,MAAI,KACF,sBAAqB,UAAU;AAGjC,SAAO;IACN;EAAC;EAAe;EAAS;EAAY,CAAC;CAEzC,MAAM,iBAAiB,MAAM,aAC1B,YAAmC;;AAClC,uBAAqB,4CAChB,gBACH,yCAAgB,QAAQ,uFAAkB;AAE5C,UAAQ,KAAK;AACb,0BAAwB;IAE1B,CAAC,wBAAwB,QAAQ,CAClC;AAED,OAAM,gBAAgB;AACpB,0BAAwB;IACvB,CAAC,uBAAuB,CAAC;CAE5B,MAAM,qBAAqB,MAAM,aAC9B,SAA+B;AAC9B,wBAAsB,QAAQ,IAAI,KAAK,WAAW,MAAM,KAAK;AAC7D,MAAI,CAAC,WAAW,CAAC,cACf;AAGF,cAAY;GACV,MAAM;GACN,OAAO,CAAC,KAAK,WAAW;GACzB,CAAC;IAEJ;EAAC;EAAe;EAAS;EAAY,CACtC;CAED,MAAM,uBAAuB,MAAM,aAChC,SAAiB;AAEhB,MAAI,CADY,sBAAsB,QAAQ,OAAO,KAAK,IAC1C,CAAC,WAAW,CAAC,cAC3B;AAGF,cAAY;GACV,MAAM;GACN,OAAO,CAAC,KAAK;GACd,CAAC;IAEJ;EAAC;EAAe;EAAS;EAAY,CACtC;AAED,OAAM,gBAAgB;AACpB,MAAI,CAAC,WAAW,CAAC,cACf;EAGF,MAAM,QAAQ,CAAC,GAAG,sBAAsB,QAAQ,QAAQ,CAAC,CAAC,KACvD,SAAS,KAAK,WAChB;AACD,MAAI,MAAM,WAAW,EACnB;AAGF,cAAY;GACV,MAAM;GACN;GACD,CAAC;IACD;EAAC;EAAe;EAAS;EAAY,CAAC;AAGzC,OAAM,gBAAgB;EACpB,MAAM,SAAS;AACf,MAAI,CAAC,OACH;EAGF,MAAM,iBAAiB,UAAuC;;AAC5D,OAAI,MAAM,WAAW,OAAO,cAC1B;AAEF,OAAI,QAAQ,IAAI,aAAa,cAC3B,SAAQ,IAAI,kBAAkB,MAAM,KAAK;AAG3C,0BAAQ,MAAM,gEAAM,MAApB;IACE,KAAK;AACH,gBAAW,KAAK;AAChB;IACF,KAAK;AACH,sBAAiB,KAAK;AACtB;IACF,KAAK;AACH,aAAQ,MAAM;AACd;IACF,KAAK;AACH,mBAAc,KAAK;AACnB;IACF,KAAK;AACH,mBAAc,MAAM;AACpB;IACF,KAAK;AACH,qBAAgB,KAAK;AACrB;IACF,KAAK;AACH,qBAAgB,MAAM;AACtB;IACF,KAAK;AAEH,YAAO,MAAM,OAAO;AACpB;IACF,KAAK,uBAAuB;KAC1B,MAAM,EAAE,QAAQ,MAAM,SAAS,MAAM;KACrC,MAAM,OAAO,sBAAsB,QAAQ,IAAI,KAAK;AACpD,SAAI,CAAC,MAAM;AACT,kBAAY;OACV,MAAM;OACN;OACA,OAAO,0BAA0B;OAClC,CAAC;AACF;;AAGF,MAAM,YAAY;AAChB,UAAI;AAEF,mBAAY;QACV,MAAM;QACN;QACA,QAJa,MAAM,KAAK,QAAQ,KAAK;QAKtC,CAAC;eACK,OAAO;AACd,mBAAY;QACV,MAAM;QACN;QACA,OAAO,eAAe,MAAM;QAC7B,CAAC;;SAEF;AACJ;;;;EAKN,MAAM,yBAAyB;AAC7B,cAAW,MAAM;AACjB,oBAAiB,MAAM;;AAGzB,SAAO,iBAAiB,WAAW,cAAc;AACjD,SAAO,iBAAiB,QAAQ,iBAAiB;AAEjD,eAAa;AACX,UAAO,oBAAoB,WAAW,cAAc;AACpD,UAAO,oBAAoB,QAAQ,iBAAiB;;IAErD,CAAC,SAAS,CAAC;AAEd,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}

package/dist/components/provider/use-chatbot-window-states.mjs

@@ -3,6 +3,31 @@
 import React from "react";
 
 //#region src/components/provider/use-chatbot-window-states.tsx
+/**
+* チャットボット UI の開閉・展開・フルスクリーン状態を管理します。
+*
+* @returns 初回オープン判定と、各表示状態、その更新関数を返します。
+*
+* @example
+* ```tsx
+* export function ChatbotWindowController() {
+*   const { open, setOpen, isExpanded, setIsExpanded } =
+*     useChatbotWindowStates();
+*
+*   return (
+*     <button
+*       type="button"
+*       onClick={() => {
+*         setOpen(!open);
+*         setIsExpanded(!isExpanded);
+*       }}
+*     >
+*       Toggle window
+*     </button>
+*   );
+* }
+* ```
+*/
 function useChatbotWindowStates() {
 	const [hasOpened, setHasOpened] = React.useState(false);
 	const [open, setOpen] = React.useState(false);

package/dist/components/provider/use-chatbot-window-states.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-chatbot-window-states.mjs","names":[],"sources":["../../../src/components/provider/use-chatbot-window-states.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\n\nexport function useChatbotWindowStates() {\n  const [hasOpened, setHasOpened] = React.useState(false);\n  const [open, setOpen] = React.useState(false);\n  const [isExpanded, setIsExpanded] = React.useState(false);\n  const [isFullScreen, setIsFullScreen] = React.useState(false);\n\n  React.useEffect(() => {\n    if (open) {\n      setHasOpened(true);\n    }\n  }, [open]);\n\n  return {\n    hasOpened,\n    open,\n    isExpanded,\n    isFullScreen,\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  };\n}\n"],"mappings":";;;;;AAIA,SAAgB,yBAAyB;CACvC,MAAM,CAAC,WAAW,gBAAgB,MAAM,SAAS,MAAM;CACvD,MAAM,CAAC,MAAM,WAAW,MAAM,SAAS,MAAM;CAC7C,MAAM,CAAC,YAAY,iBAAiB,MAAM,SAAS,MAAM;CACzD,MAAM,CAAC,cAAc,mBAAmB,MAAM,SAAS,MAAM;AAE7D,OAAM,gBAAgB;AACpB,MAAI,KACF,cAAa,KAAK;IAEnB,CAAC,KAAK,CAAC;AAEV,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"use-chatbot-window-states.mjs","names":[],"sources":["../../../src/components/provider/use-chatbot-window-states.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\n\n/**\n * チャットボット UI の開閉・展開・フルスクリーン状態を管理します。\n *\n * @returns 初回オープン判定と、各表示状態、その更新関数を返します。\n *\n * @example\n * ```tsx\n * export function ChatbotWindowController() {\n *   const { open, setOpen, isExpanded, setIsExpanded } =\n *     useChatbotWindowStates();\n *\n *   return (\n *     <button\n *       type=\"button\"\n *       onClick={() => {\n *         setOpen(!open);\n *         setIsExpanded(!isExpanded);\n *       }}\n *     >\n *       Toggle window\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useChatbotWindowStates() {\n  const [hasOpened, setHasOpened] = React.useState(false);\n  const [open, setOpen] = React.useState(false);\n  const [isExpanded, setIsExpanded] = React.useState(false);\n  const [isFullScreen, setIsFullScreen] = React.useState(false);\n\n  React.useEffect(() => {\n    if (open) {\n      setHasOpened(true);\n    }\n  }, [open]);\n\n  return {\n    hasOpened,\n    open,\n    isExpanded,\n    isFullScreen,\n    setOpen,\n    setIsExpanded,\n    setIsFullScreen,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,yBAAyB;CACvC,MAAM,CAAC,WAAW,gBAAgB,MAAM,SAAS,MAAM;CACvD,MAAM,CAAC,MAAM,WAAW,MAAM,SAAS,MAAM;CAC7C,MAAM,CAAC,YAAY,iBAAiB,MAAM,SAAS,MAAM;CACzD,MAAM,CAAC,cAAc,mBAAmB,MAAM,SAAS,MAAM;AAE7D,OAAM,gBAAgB;AACpB,MAAI,KACF,cAAa,KAAK;IAEnB,CAAC,KAAK,CAAC;AAEV,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}

package/dist/components/sheet.d.mts

@@ -1,11 +1,11 @@
 import * as React$1 from "react";
-import * as react_jsx_runtime3 from "react/jsx-runtime";
+import * as react_jsx_runtime2 from "react/jsx-runtime";
 import * as SheetPrimitive from "@radix-ui/react-dialog";
 
 //#region src/components/sheet.d.ts
 declare function Sheet({
   ...props
-}: React$1.ComponentProps<typeof SheetPrimitive.Root>): react_jsx_runtime3.JSX.Element;
+}: React$1.ComponentProps<typeof SheetPrimitive.Root>): react_jsx_runtime2.JSX.Element;
 declare const SheetTrigger: React$1.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogTriggerProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
 declare const SheetClose: React$1.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogCloseProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
 declare const SheetContent: React$1.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;

package/dist/components/tooltip.d.mts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime3 from "react/jsx-runtime";
 
 //#region src/components/tooltip.d.ts
 type Side = "top" | "right" | "bottom" | "left";
@@ -32,7 +32,7 @@ declare function Tooltip({
   sideOffset,
   arrowClassName,
   keepTooltipOpen
-}: TooltipProps): react_jsx_runtime0.JSX.Element;
+}: TooltipProps): react_jsx_runtime3.JSX.Element;
 //#endregion
 export { Tooltip };
 //# sourceMappingURL=tooltip.d.mts.map

package/dist/index.d.mts

@@ -1,6 +1,7 @@
+import { ClientToolDefinition, ClientToolExecuteRequest, ClientToolJsonSchema, RegisteredClientTool, UseClientToolOptions, useClientTool } from "./lib/client-tools.mjs";
 import { ChatbotProvider, useChatbot } from "./components/provider/chatbot-provider.mjs";
 import { ChatbotFrame, ChatbotFrameProps, SessionData, UseSessionProps, useSession } from "./components/chatbot-frame.mjs";
 import { ChatbotSheet } from "./components/chatbot-sheet.mjs";
 import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "./components/sheet.mjs";
 import { Tooltip } from "./components/tooltip.mjs";
-export { ChatbotFrame, ChatbotFrameProps, ChatbotProvider, ChatbotSheet, SessionData, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Tooltip, UseSessionProps, useChatbot, useSession };
+export { ChatbotFrame, ChatbotFrameProps, ChatbotProvider, ChatbotSheet, ClientToolDefinition, ClientToolExecuteRequest, ClientToolJsonSchema, RegisteredClientTool, SessionData, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Tooltip, UseClientToolOptions, UseSessionProps, useChatbot, useClientTool, useSession };

package/dist/index.mjs

@@ -3,5 +3,6 @@ import { ChatbotFrame, useSession } from "./components/chatbot-frame.mjs";
 import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "./components/sheet.mjs";
 import { Tooltip } from "./components/tooltip.mjs";
 import { ChatbotSheet } from "./components/chatbot-sheet.mjs";
+import { useClientTool } from "./lib/client-tools.mjs";
 
-export { ChatbotFrame, ChatbotProvider, ChatbotSheet, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Tooltip, useChatbot, useSession };
+export { ChatbotFrame, ChatbotProvider, ChatbotSheet, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Tooltip, useChatbot, useClientTool, useSession };

package/dist/lib/client-tools.d.mts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+
+//#region src/lib/client-tools.d.ts
+type ClientToolJsonSchema = Record<string, unknown>;
+type ClientToolDefinition = {
+  name: string;
+  displayName: string;
+  description: string;
+  summary?: string;
+  requireConfirmation?: boolean;
+  parameters: ClientToolJsonSchema;
+};
+type ClientToolExecuteRequest = {
+  callId: string;
+  name: string;
+  args: unknown;
+};
+type RegisteredClientTool = {
+  definition: ClientToolDefinition;
+  execute: (args: unknown) => Promise<unknown> | unknown;
+};
+type UseClientToolOptions<TParameters extends z.ZodTypeAny> = {
+  /** ツール名です。`page_`のプレフィックスが自動で追加されます。 */
+  name: string;
+  /** UI上に表示するツール名です。 */
+  displayName: string;
+  /** LLMが見れるツールの詳細説明です。 */
+  description: string;
+  /** ユーザーに表示するツールの要約です。 */
+  summary?: string;
+  /** 実行前にユーザー確認を要求するかを指定します。 */
+  requireConfirmation?: boolean;
+  /** ツールの引数を定義するZodスキーマです。 */
+  parameters: TParameters;
+  /** 検証済み引数を受け取り、ツール本体の処理を実行します。 */
+  execute: (args: z.output<TParameters>) => Promise<unknown> | unknown;
+};
+/**
+ * チャットボットから呼び出せるクライアントツールを登録します。
+ *
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { useClientTool } from "@super_studio/ecforce-ai-agent-react";
+ *
+ * export function InventoryToolRegistration() {
+ *   useClientTool({
+ *     name: "lookup_inventory",
+ *     displayName: "在庫確認",
+ *     description: "商品コードから在庫数を取得します。",
+ *     summary: "商品在庫を返します。",
+ *     parameters: z.object({
+ *       sku: z.string().describe("商品コード"),
+ *     }),
+ *     execute: async ({ sku }) => {
+ *       return { sku, available: true };
+ *     },
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+declare function useClientTool<TParameters extends z.ZodTypeAny>({
+  name,
+  displayName,
+  description,
+  summary,
+  requireConfirmation,
+  parameters,
+  execute
+}: UseClientToolOptions<TParameters>): void;
+//#endregion
+export { ClientToolDefinition, ClientToolExecuteRequest, ClientToolJsonSchema, RegisteredClientTool, UseClientToolOptions, useClientTool };
+//# sourceMappingURL=client-tools.d.mts.map