@super_studio/ecforce-ai-agent-react 1.1.1 → 1.2.0-canary.0

package/dist/components/ai-icon.mjs

@@ -1,18 +1,17 @@
+import { PROD_CHATBOT_URL } from "../lib/constants.mjs";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/components/ai-icon.tsx
-function AiIcon({ width = 18, height = 18 }) {
-	return /* @__PURE__ */ jsx("svg", {
+const AI_ICON_GIF_URL = new URL("/images/ai-icon.gif", PROD_CHATBOT_URL).toString();
+function AiIcon({ width = 24, height = 24 }) {
+	return /* @__PURE__ */ jsx("img", {
+		src: AI_ICON_GIF_URL,
 		width,
 		height,
-		viewBox: "0 0 24 24",
-		fill: "currentColor",
+		alt: "",
 		"aria-hidden": "true",
-		children: /* @__PURE__ */ jsx("path", {
-			fillRule: "evenodd",
-			clipRule: "evenodd",
-			d: "M9.2 13.704s3.7-.812 4.325-3.74c.624-2.93.76-3.364 1.112-3.364.352 0 .42.309.5.618.08.309.51 2.276.613 2.745.102.47.783 2.93 3.712 3.616 2.93.686 3.338.697 3.338 1.12 0 .459-2.361.859-3.338 1.122-.976.263-3.042 1.007-3.587 3.49-.534 2.482-.681 3.489-1.238 3.489-.556 0-.545-.584-.613-.87-.068-.286-.34-1.819-.5-2.494-.147-.675-1.044-2.837-2.962-3.363-1.93-.527-3.962-.847-3.962-1.373s2.134-.824 2.6-.995ZM2.462 4.613s1.785-.39 2.08-1.798c.296-1.409.365-1.615.535-1.615.17 0 .205.149.239.298s.25 1.088.296 1.317c.045.229.375 1.409 1.785 1.74 1.41.333 1.603.333 1.603.54 0 .217-1.137.412-1.603.538-.466.126-1.467.48-1.729 1.683C5.407 8.507 5.338 9 5.078 9c-.262 0-.262-.286-.296-.424-.035-.137-.16-.882-.24-1.202-.079-.321-.5-1.363-1.432-1.615-.932-.252-1.91-.413-1.91-.665 0-.252 1.023-.4 1.25-.48h.012Z"
-		})
+		draggable: false,
+		style: { display: "block" }
 	});
 }
 

package/dist/components/ai-icon.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai-icon.mjs","names":[],"sources":["../../src/components/ai-icon.tsx"],"sourcesContent":["type AiIconProps = {\n  width?: number;\n  height?: number;\n};\n\nexport function AiIcon({ width = 18, height = 18 }: AiIconProps) {\n  return (\n    <svg\n      width={width}\n      height={height}\n      viewBox=\"0 0 24 24\"\n      fill=\"currentColor\"\n      aria-hidden=\"true\"\n    >\n      <path\n        fillRule=\"evenodd\"\n        clipRule=\"evenodd\"\n        d=\"M9.2 13.704s3.7-.812 4.325-3.74c.624-2.93.76-3.364 1.112-3.364.352 0 .42.309.5.618.08.309.51 2.276.613 2.745.102.47.783 2.93 3.712 3.616 2.93.686 3.338.697 3.338 1.12 0 .459-2.361.859-3.338 1.122-.976.263-3.042 1.007-3.587 3.49-.534 2.482-.681 3.489-1.238 3.489-.556 0-.545-.584-.613-.87-.068-.286-.34-1.819-.5-2.494-.147-.675-1.044-2.837-2.962-3.363-1.93-.527-3.962-.847-3.962-1.373s2.134-.824 2.6-.995ZM2.462 4.613s1.785-.39 2.08-1.798c.296-1.409.365-1.615.535-1.615.17 0 .205.149.239.298s.25 1.088.296 1.317c.045.229.375 1.409 1.785 1.74 1.41.333 1.603.333 1.603.54 0 .217-1.137.412-1.603.538-.466.126-1.467.48-1.729 1.683C5.407 8.507 5.338 9 5.078 9c-.262 0-.262-.286-.296-.424-.035-.137-.16-.882-.24-1.202-.079-.321-.5-1.363-1.432-1.615-.932-.252-1.91-.413-1.91-.665 0-.252 1.023-.4 1.25-.48h.012Z\"\n      />\n    </svg>\n  );\n}\n"],"mappings":";;;AAKA,SAAgB,OAAO,EAAE,QAAQ,IAAI,SAAS,MAAmB;AAC/D,QACE,oBAAC;EACQ;EACC;EACR,SAAQ;EACR,MAAK;EACL,eAAY;YAEZ,oBAAC;GACC,UAAS;GACT,UAAS;GACT,GAAE;IACF;GACE"}
+{"version":3,"file":"ai-icon.mjs","names":[],"sources":["../../src/components/ai-icon.tsx"],"sourcesContent":["import { PROD_CHATBOT_URL } from \"../lib/constants\";\n\ntype AiIconProps = {\n  width?: number;\n  height?: number;\n};\n\nconst AI_ICON_GIF_URL = new URL(\n  \"/images/ai-icon.gif\",\n  PROD_CHATBOT_URL,\n).toString();\n\nexport function AiIcon({ width = 24, height = 24 }: AiIconProps) {\n  return (\n    <img\n      src={AI_ICON_GIF_URL}\n      width={width}\n      height={height}\n      alt=\"\"\n      aria-hidden=\"true\"\n      draggable={false}\n      style={{ display: \"block\" }}\n    />\n  );\n}\n"],"mappings":";;;;AAOA,MAAM,kBAAkB,IAAI,IAC1B,uBACA,iBACD,CAAC,UAAU;AAEZ,SAAgB,OAAO,EAAE,QAAQ,IAAI,SAAS,MAAmB;AAC/D,QACE,oBAAC;EACC,KAAK;EACE;EACC;EACR,KAAI;EACJ,eAAY;EACZ,WAAW;EACX,OAAO,EAAE,SAAS,SAAS;GAC3B"}

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/chatbot-sheet.mjs

@@ -18,8 +18,8 @@ function ChatbotSheet(_ref) {
 		align: "end",
 		content: "AIに質問してみましょう",
 		trigger: /* @__PURE__ */ jsx(SheetTrigger, { children: /* @__PURE__ */ jsx(AiIcon, {
-			width: 18,
-			height: 18
+			width: 24,
+			height: 24
 		}) })
 	}), /* @__PURE__ */ jsxs(SheetContent, {
 		style: sheetStyle,

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

@@ -1 +1 @@
-{"version":3,"file":"chatbot-sheet.mjs","names":[],"sources":["../../src/components/chatbot-sheet.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport { AiIcon } from \"./ai-icon\";\nimport { ChatbotFrame, type ChatbotFrameProps } from \"./chatbot-frame\";\nimport {\n  Sheet,\n  SheetContent,\n  SheetDescription,\n  SheetTitle,\n  SheetTrigger,\n} from \"./sheet\";\nimport { Tooltip } from \"./tooltip\";\n\ntype ChatbotSheetProps = ChatbotFrameProps & {\n  sheetStyle?: React.CSSProperties;\n};\n\nexport function ChatbotSheet({ sheetStyle, ...props }: ChatbotSheetProps) {\n  return (\n    <Sheet>\n      <Tooltip\n        side=\"top\"\n        align=\"end\"\n        content=\"AIに質問してみましょう\"\n        trigger={\n          <SheetTrigger>\n            <AiIcon width={18} height={18} />\n          </SheetTrigger>\n        }\n      />\n      <SheetContent style={sheetStyle}>\n        <SheetTitle>AIに質問してみましょう</SheetTitle>\n        <SheetDescription>AIに質問してみましょう</SheetDescription>\n        <ChatbotFrame {...props} />\n      </SheetContent>\n    </Sheet>\n  );\n}\n"],"mappings":";;;;;;;;;;;;mBAkB+B;AAA/B,SAAgB,aAAa,MAA6C;KAA7C,EAAE,qBAAe;AAC5C,QACE,qBAAC,oBACC,oBAAC;EACC,MAAK;EACL,OAAM;EACN,SAAQ;EACR,SACE,oBAAC,0BACC,oBAAC;GAAO,OAAO;GAAI,QAAQ;IAAM,GACpB;GAEjB,EACF,qBAAC;EAAa,OAAO;;GACnB,oBAAC,wBAAW,iBAAyB;GACrC,oBAAC,8BAAiB,iBAA+B;GACjD,oBAAC,iCAAiB,OAAS;;GACd,IACT"}
+{"version":3,"file":"chatbot-sheet.mjs","names":[],"sources":["../../src/components/chatbot-sheet.tsx"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport { AiIcon } from \"./ai-icon\";\nimport { ChatbotFrame, type ChatbotFrameProps } from \"./chatbot-frame\";\nimport {\n  Sheet,\n  SheetContent,\n  SheetDescription,\n  SheetTitle,\n  SheetTrigger,\n} from \"./sheet\";\nimport { Tooltip } from \"./tooltip\";\n\ntype ChatbotSheetProps = ChatbotFrameProps & {\n  sheetStyle?: React.CSSProperties;\n};\n\nexport function ChatbotSheet({ sheetStyle, ...props }: ChatbotSheetProps) {\n  return (\n    <Sheet>\n      <Tooltip\n        side=\"top\"\n        align=\"end\"\n        content=\"AIに質問してみましょう\"\n        trigger={\n          <SheetTrigger>\n            <AiIcon width={24} height={24} />\n          </SheetTrigger>\n        }\n      />\n      <SheetContent style={sheetStyle}>\n        <SheetTitle>AIに質問してみましょう</SheetTitle>\n        <SheetDescription>AIに質問してみましょう</SheetDescription>\n        <ChatbotFrame {...props} />\n      </SheetContent>\n    </Sheet>\n  );\n}\n"],"mappings":";;;;;;;;;;;;mBAkB+B;AAA/B,SAAgB,aAAa,MAA6C;KAA7C,EAAE,qBAAe;AAC5C,QACE,qBAAC,oBACC,oBAAC;EACC,MAAK;EACL,OAAM;EACN,SAAQ;EACR,SACE,oBAAC,0BACC,oBAAC;GAAO,OAAO;GAAI,QAAQ;IAAM,GACpB;GAEjB,EACF,qBAAC;EAAa,OAAO;;GACnB,oBAAC,wBAAW,iBAAyB;GACrC,oBAAC,8BAAiB,iBAA+B;GACjD,oBAAC,iCAAiB,OAAS;;GACd,IACT"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.d.mts","names":[],"sources":["../../src/lib/client-tools.ts"],"sourcesContent":[],"mappings":";;;KAMY,oBAAA,GAAuB;KAGvB,oBAAA;EAHA,IAAA,EAAA,MAAA;EAGA,WAAA,EAAA,MAAA;EASA,WAAA,EAAA,MAAA;EAMA,OAAA,CAAA,EAAA,MAAA;EAKA,mBAAA,CAAA,EAAA,OAAoB;EAAuB,UAAA,EAdzC,oBAcyC;CAYzC;AAEa,KAzBf,wBAAA,GAyBe;EAAP,MAAA,EAAA,MAAA;EAAwB,IAAA,EAAA,MAAA;EAAO,IAAA,EAAA,OAAA;AAqCnD,CAAA;AAAoD,KAxDxC,oBAAA,GAwDwC;EAClD,UAAA,EAxDY,oBAwDZ;EACA,OAAA,EAAA,CAAA,IAAA,EAAA,OAAA,EAAA,GAxD4B,OAwD5B,CAAA,OAAA,CAAA,GAAA,OAAA;CACA;AACA,KAvDU,oBAuDV,CAAA,oBAvDmD,CAAA,CAAE,UAuDrD,CAAA,GAAA;EACA;EACA,IAAA,EAAA,MAAA;EACA;EACsB,WAAA,EAAA,MAAA;EAArB;EAAoB,WAAA,EAAA,MAAA;;;;;;cA/CT;;kBAEI,CAAA,CAAE,OAAO,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqC5B,kCAAkC,CAAA,CAAE;;;;;;;;GAQjD,qBAAqB"}

package/dist/lib/client-tools.mjs

@@ -0,0 +1,80 @@
+"use client";
+
+import { useChatbot } from "../components/provider/chatbot-provider.mjs";
+import React from "react";
+
+//#region src/lib/client-tools.ts
+const CLIENT_TOOL_NAME_PREFIX = "page_";
+function normalizeClientToolName(name) {
+	if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) return name;
+	return `${CLIENT_TOOL_NAME_PREFIX}${name}`;
+}
+/**
+* チャットボットから呼び出せるクライアントツールを登録します。
+*
+* @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;
+* }
+* ```
+*/
+function useClientTool({ name, displayName, description, summary, requireConfirmation = false, parameters, execute }) {
+	const { registerClientTool, unregisterClientTool } = useChatbot();
+	const executeRef = React.useRef(execute);
+	const normalizedName = React.useMemo(() => normalizeClientToolName(name), [name]);
+	React.useEffect(() => {
+		executeRef.current = execute;
+	}, [execute]);
+	React.useEffect(() => {
+		let isCancelled = false;
+		(async () => {
+			const { z } = await import("zod");
+			if (isCancelled) return;
+			registerClientTool({
+				definition: {
+					name: normalizedName,
+					displayName,
+					description,
+					summary,
+					requireConfirmation,
+					parameters: z.toJSONSchema(parameters)
+				},
+				execute: (args) => executeRef.current(args)
+			});
+		})();
+		return () => {
+			isCancelled = true;
+			unregisterClientTool(normalizedName);
+		};
+	}, [
+		description,
+		displayName,
+		normalizedName,
+		parameters,
+		registerClientTool,
+		requireConfirmation,
+		summary,
+		unregisterClientTool
+	]);
+}
+
+//#endregion
+export { useClientTool };
+//# sourceMappingURL=client-tools.mjs.map

package/dist/lib/client-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.mjs","names":[],"sources":["../../src/lib/client-tools.ts"],"sourcesContent":["\"use client\";\n\nimport React from \"react\";\nimport type { z } from \"zod\";\nimport { useChatbot } from \"../components/provider/chatbot-provider\";\n\nexport type ClientToolJsonSchema = Record<string, unknown>;\nconst CLIENT_TOOL_NAME_PREFIX = \"page_\";\n\nexport type ClientToolDefinition = {\n  name: string;\n  displayName: string;\n  description: string;\n  summary?: string;\n  requireConfirmation?: boolean;\n  parameters: ClientToolJsonSchema;\n};\n\nexport type ClientToolExecuteRequest = {\n  callId: string;\n  name: string;\n  args: unknown;\n};\n\nexport type RegisteredClientTool = {\n  definition: ClientToolDefinition;\n  execute: (args: unknown) => Promise<unknown> | unknown;\n};\n\nexport type UseClientToolOptions<TParameters extends z.ZodTypeAny> = {\n  /** ツール名です。`page_`のプレフィックスが自動で追加されます。 */\n  name: string;\n  /** UI上に表示するツール名です。 */\n  displayName: string;\n  /** LLMが見れるツールの詳細説明です。 */\n  description: string;\n  /** ユーザーに表示するツールの要約です。 */\n  summary?: string;\n  /** 実行前にユーザー確認を要求するかを指定します。 */\n  requireConfirmation?: boolean;\n  /** ツールの引数を定義するZodスキーマです。 */\n  parameters: TParameters;\n  /** 検証済み引数を受け取り、ツール本体の処理を実行します。 */\n  execute: (args: z.output<TParameters>) => Promise<unknown> | unknown;\n};\n\nfunction normalizeClientToolName(name: string) {\n  if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) {\n    return name;\n  }\n\n  return `${CLIENT_TOOL_NAME_PREFIX}${name}`;\n}\n\n/**\n * チャットボットから呼び出せるクライアントツールを登録します。\n *\n * @example\n * ```tsx\n * import { z } from \"zod\";\n * import { useClientTool } from \"@super_studio/ecforce-ai-agent-react\";\n *\n * export function InventoryToolRegistration() {\n *   useClientTool({\n *     name: \"lookup_inventory\",\n *     displayName: \"在庫確認\",\n *     description: \"商品コードから在庫数を取得します。\",\n *     summary: \"商品在庫を返します。\",\n *     parameters: z.object({\n *       sku: z.string().describe(\"商品コード\"),\n *     }),\n *     execute: async ({ sku }) => {\n *       return { sku, available: true };\n *     },\n *   });\n *\n *   return null;\n * }\n * ```\n */\nexport function useClientTool<TParameters extends z.ZodTypeAny>({\n  name,\n  displayName,\n  description,\n  summary,\n  requireConfirmation = false,\n  parameters,\n  execute,\n}: UseClientToolOptions<TParameters>) {\n  const { registerClientTool, unregisterClientTool } = useChatbot();\n  const executeRef = React.useRef(execute);\n  const normalizedName = React.useMemo(\n    () => normalizeClientToolName(name),\n    [name],\n  );\n\n  React.useEffect(() => {\n    executeRef.current = execute;\n  }, [execute]);\n\n  React.useEffect(() => {\n    let isCancelled = false;\n\n    void (async () => {\n      const { z } = await import(\"zod\");\n      if (isCancelled) {\n        return;\n      }\n\n      registerClientTool({\n        definition: {\n          name: normalizedName,\n          displayName,\n          description,\n          summary,\n          requireConfirmation,\n          parameters: z.toJSONSchema(parameters),\n        },\n        execute: (args) => executeRef.current(args as z.output<TParameters>),\n      });\n    })();\n\n    return () => {\n      isCancelled = true;\n      unregisterClientTool(normalizedName);\n    };\n  }, [\n    description,\n    displayName,\n    normalizedName,\n    parameters,\n    registerClientTool,\n    requireConfirmation,\n    summary,\n    unregisterClientTool,\n  ]);\n}\n"],"mappings":";;;;;;AAOA,MAAM,0BAA0B;AAuChC,SAAS,wBAAwB,MAAc;AAC7C,KAAI,KAAK,WAAW,wBAAwB,CAC1C,QAAO;AAGT,QAAO,GAAG,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BtC,SAAgB,cAAgD,EAC9D,MACA,aACA,aACA,SACA,sBAAsB,OACtB,YACA,WACoC;CACpC,MAAM,EAAE,oBAAoB,yBAAyB,YAAY;CACjE,MAAM,aAAa,MAAM,OAAO,QAAQ;CACxC,MAAM,iBAAiB,MAAM,cACrB,wBAAwB,KAAK,EACnC,CAAC,KAAK,CACP;AAED,OAAM,gBAAgB;AACpB,aAAW,UAAU;IACpB,CAAC,QAAQ,CAAC;AAEb,OAAM,gBAAgB;EACpB,IAAI,cAAc;AAElB,GAAM,YAAY;GAChB,MAAM,EAAE,MAAM,MAAM,OAAO;AAC3B,OAAI,YACF;AAGF,sBAAmB;IACjB,YAAY;KACV,MAAM;KACN;KACA;KACA;KACA;KACA,YAAY,EAAE,aAAa,WAAW;KACvC;IACD,UAAU,SAAS,WAAW,QAAQ,KAA8B;IACrE,CAAC;MACA;AAEJ,eAAa;AACX,iBAAc;AACd,wBAAqB,eAAe;;IAErC;EACD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super_studio/ecforce-ai-agent-react",
-  "version": "1.1.1",
+  "version": "1.2.0-canary.0",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -24,14 +24,21 @@
   },
   "peerDependencies": {
     "react": ">=16",
-    "react-dom": ">=16"
+    "react-dom": ">=16",
+    "zod": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "22.14.0",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "zod": "4.1.12"
   },
   "scripts": {
     "dev": "tsdown --watch",

package/src/components/ai-icon.tsx

@@ -1,22 +1,25 @@
+import { PROD_CHATBOT_URL } from "../lib/constants";
+
 type AiIconProps = {
   width?: number;
   height?: number;
 };
 
-export function AiIcon({ width = 18, height = 18 }: AiIconProps) {
+const AI_ICON_GIF_URL = new URL(
+  "/images/ai-icon.gif",
+  PROD_CHATBOT_URL,
+).toString();
+
+export function AiIcon({ width = 24, height = 24 }: AiIconProps) {
   return (
-    <svg
+    <img
+      src={AI_ICON_GIF_URL}
       width={width}
       height={height}
-      viewBox="0 0 24 24"
-      fill="currentColor"
+      alt=""
       aria-hidden="true"
-    >
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M9.2 13.704s3.7-.812 4.325-3.74c.624-2.93.76-3.364 1.112-3.364.352 0 .42.309.5.618.08.309.51 2.276.613 2.745.102.47.783 2.93 3.712 3.616 2.93.686 3.338.697 3.338 1.12 0 .459-2.361.859-3.338 1.122-.976.263-3.042 1.007-3.587 3.49-.534 2.482-.681 3.489-1.238 3.489-.556 0-.545-.584-.613-.87-.068-.286-.34-1.819-.5-2.494-.147-.675-1.044-2.837-2.962-3.363-1.93-.527-3.962-.847-3.962-1.373s2.134-.824 2.6-.995ZM2.462 4.613s1.785-.39 2.08-1.798c.296-1.409.365-1.615.535-1.615.17 0 .205.149.239.298s.25 1.088.296 1.317c.045.229.375 1.409 1.785 1.74 1.41.333 1.603.333 1.603.54 0 .217-1.137.412-1.603.538-.466.126-1.467.48-1.729 1.683C5.407 8.507 5.338 9 5.078 9c-.262 0-.262-.286-.296-.424-.035-.137-.16-.882-.24-1.202-.079-.321-.5-1.363-1.432-1.615-.932-.252-1.91-.413-1.91-.665 0-.252 1.023-.4 1.25-.48h.012Z"
-      />
-    </svg>
+      draggable={false}
+      style={{ display: "block" }}
+    />
   );
 }

package/src/components/chatbot-sheet.tsx

@@ -25,7 +25,7 @@ export function ChatbotSheet({ sheetStyle, ...props }: ChatbotSheetProps) {
         content="AIに質問してみましょう"
         trigger={
           <SheetTrigger>
-            <AiIcon width={18} height={18} />
+            <AiIcon width={24} height={24} />
           </SheetTrigger>
         }
       />

package/src/components/provider/chatbot-provider.tsx

@@ -1,11 +1,12 @@
 "use client";
 
 import React from "react";
+import type { RegisteredClientTool } from "../../lib/client-tools";
 import {
-  type SendAppMessagePayload,
   useChatbotFrameHandler,
   type InitProps,
   type MCP,
+  type SendAppMessagePayload,
 } from "./use-chatbot-frame-handler";
 import { useChatbotWindowStates } from "./use-chatbot-window-states";
 
@@ -34,6 +35,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;
   /** チャットボットが初期化されたか */
@@ -49,6 +54,34 @@ const ChatbotContext = React.createContext<ChatbotContextType | undefined>(
   undefined,
 );
 
+/**
+ * `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>
+ *   );
+ * }
+ * ```
+ */
 export function useChatbot() {
   const context = React.useContext(ChatbotContext);
   if (!context) {
@@ -76,6 +109,8 @@ export function ChatbotProvider({ children }: ChatbotProviderProps) {
     setAppName,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     init,
     isReady,
     isInitialized,
@@ -96,6 +131,8 @@ export function ChatbotProvider({ children }: ChatbotProviderProps) {
     setIsFullScreen,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     init,
     setMcps,
     setAppName,

package/src/components/provider/use-chatbot-frame-handler.tsx

@@ -1,6 +1,11 @@
 "use client";
 
 import React from "react";
+import type {
+  ClientToolDefinition,
+  ClientToolExecuteRequest,
+  RegisteredClientTool,
+} from "../../lib/client-tools";
 
 export type IframeMessage =
   | { type: "CHATBOT_READY" }
@@ -10,7 +15,10 @@ export type IframeMessage =
   | { type: "SHRINK_CHATBOT" }
   | { type: "FULLSCREEN_CHATBOT" }
   | { type: "EXIT_FULLSCREEN_CHATBOT" }
-  | { type: "RELOAD_CHATBOT" };
+  | { type: "RELOAD_CHATBOT" }
+  | ({
+      type: "EXECUTE_CLIENT_TOOL";
+    } & ClientToolExecuteRequest);
 
 export type MCP = {
   name: string;
@@ -25,16 +33,24 @@ export type InitProps = {
 };
 
 export type AppMessageAttachment = {
+  /** 添付ファイルの表示名です。 */
   fileName: string;
+  /** 添付ファイルの MIME type です。 */
   mediaType: string;
+  /** 添付ファイルを取得できる URL です。 */
   url: string;
 };
 
 export type SendAppMessagePayload = {
+  /** チャット上に表示するタイトルです。 */
   title?: string;
+  /** ユーザーに表示するメッセージ本文です。 */
   message: string;
+  /** UI に表示せず、裏側のコンテキストとして渡すメッセージです。 */
   hiddenMessage?: string;
+  /** 新規チャットを開始してから送るかを指定します。 */
   startOnNewChat?: boolean;
+  /** メッセージと一緒に渡す添付ファイル一覧です。 */
   attachments?: AppMessageAttachment[];
 };
 
@@ -60,23 +76,86 @@ export type ParentMessage =
   | {
       type: "appMessage";
       payload: SendAppMessagePayload;
+    }
+  | {
+      type: "registerClientTools";
+      tools: ClientToolDefinition[];
+    }
+  | {
+      type: "unregisterClientTools";
+      names: string[];
+    }
+  | {
+      type: "clientToolResult";
+      callId: string;
+      result?: unknown;
+      error?: string;
     };
 
+function serializeError(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === "string") {
+    return error;
+  }
+
+  return "Unknown client tool error";
+}
+
+type UseChatbotFrameHandlerProps = {
+  /** チャットボットの開閉状態を更新します。 */
+  setOpen: (open: boolean) => void;
+  /** 展開状態を更新します。 */
+  setIsExpanded: (expanded: boolean) => void;
+  /** フルスクリーン状態を更新します。 */
+  setIsFullScreen: (fullScreen: boolean) => void;
+};
+
+/**
+ * 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" />;
+ * }
+ * ```
+ */
 export function useChatbotFrameHandler({
   setOpen,
   setIsExpanded,
   setIsFullScreen,
-}: {
-  setOpen: (open: boolean) => void;
-  setIsExpanded: (expanded: boolean) => void;
-  setIsFullScreen: (fullScreen: boolean) => void;
-}) {
+}: UseChatbotFrameHandlerProps) {
   const [iframeEl, setIframeEl] = React.useState<HTMLIFrameElement | null>(
     null,
   );
   const [isReady, setIsReady] = React.useState(false);
   const [isInitialized, setIsInitialized] = React.useState(false);
   const pendingAppMessageRef = React.useRef<SendAppMessagePayload | null>(null);
+  const clientToolRegistryRef = React.useRef(
+    new Map<string, RegisteredClientTool>(),
+  );
 
   // helper to post message to the iframe
   const postMessage = React.useCallback(
@@ -158,6 +237,54 @@ export function useChatbotFrameHandler({
     flushPendingAppMessage();
   }, [flushPendingAppMessage]);
 
+  const registerClientTool = React.useCallback(
+    (tool: RegisteredClientTool) => {
+      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: string) => {
+      const deleted = clientToolRegistryRef.current.delete(name);
+      if (!deleted || !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]);
+
   // Initialize and setup listeners
   React.useEffect(() => {
     const iframe = iframeEl;
@@ -199,6 +326,36 @@ export function useChatbotFrameHandler({
           // reload iframe
           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;
+          }
+
+          void (async () => {
+            try {
+              const result = await tool.execute(args);
+              postMessage({
+                type: "clientToolResult",
+                callId,
+                result,
+              });
+            } catch (error) {
+              postMessage({
+                type: "clientToolResult",
+                callId,
+                error: serializeError(error),
+              });
+            }
+          })();
+          break;
+        }
       }
     };
 
@@ -222,6 +379,8 @@ export function useChatbotFrameHandler({
     setAppName,
     setSessionToken,
     sendAppMessage,
+    registerClientTool,
+    unregisterClientTool,
     setIframeEl,
     isReady,
     isInitialized,

package/src/components/provider/use-chatbot-window-states.tsx

@@ -2,6 +2,31 @@
 
 import React from "react";
 
+/**
+ * チャットボット 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>
+ *   );
+ * }
+ * ```
+ */
 export function useChatbotWindowStates() {
   const [hasOpened, setHasOpened] = React.useState(false);
   const [open, setOpen] = React.useState(false);

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./components/chatbot-frame";
 export * from "./components/chatbot-sheet";
 export * from "./components/sheet";
 export * from "./components/tooltip";
+export * from "./lib/client-tools";

package/src/lib/client-tools.ts

@@ -0,0 +1,137 @@
+"use client";
+
+import React from "react";
+import type { z } from "zod";
+import { useChatbot } from "../components/provider/chatbot-provider";
+
+export type ClientToolJsonSchema = Record<string, unknown>;
+const CLIENT_TOOL_NAME_PREFIX = "page_";
+
+export type ClientToolDefinition = {
+  name: string;
+  displayName: string;
+  description: string;
+  summary?: string;
+  requireConfirmation?: boolean;
+  parameters: ClientToolJsonSchema;
+};
+
+export type ClientToolExecuteRequest = {
+  callId: string;
+  name: string;
+  args: unknown;
+};
+
+export type RegisteredClientTool = {
+  definition: ClientToolDefinition;
+  execute: (args: unknown) => Promise<unknown> | unknown;
+};
+
+export 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;
+};
+
+function normalizeClientToolName(name: string) {
+  if (name.startsWith(CLIENT_TOOL_NAME_PREFIX)) {
+    return name;
+  }
+
+  return `${CLIENT_TOOL_NAME_PREFIX}${name}`;
+}
+
+/**
+ * チャットボットから呼び出せるクライアントツールを登録します。
+ *
+ * @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;
+ * }
+ * ```
+ */
+export function useClientTool<TParameters extends z.ZodTypeAny>({
+  name,
+  displayName,
+  description,
+  summary,
+  requireConfirmation = false,
+  parameters,
+  execute,
+}: UseClientToolOptions<TParameters>) {
+  const { registerClientTool, unregisterClientTool } = useChatbot();
+  const executeRef = React.useRef(execute);
+  const normalizedName = React.useMemo(
+    () => normalizeClientToolName(name),
+    [name],
+  );
+
+  React.useEffect(() => {
+    executeRef.current = execute;
+  }, [execute]);
+
+  React.useEffect(() => {
+    let isCancelled = false;
+
+    void (async () => {
+      const { z } = await import("zod");
+      if (isCancelled) {
+        return;
+      }
+
+      registerClientTool({
+        definition: {
+          name: normalizedName,
+          displayName,
+          description,
+          summary,
+          requireConfirmation,
+          parameters: z.toJSONSchema(parameters),
+        },
+        execute: (args) => executeRef.current(args as z.output<TParameters>),
+      });
+    })();
+
+    return () => {
+      isCancelled = true;
+      unregisterClientTool(normalizedName);
+    };
+  }, [
+    description,
+    displayName,
+    normalizedName,
+    parameters,
+    registerClientTool,
+    requireConfirmation,
+    summary,
+    unregisterClientTool,
+  ]);
+}