skybridge 0.0.0-dev.f5759ba → 0.0.0-dev.f57f202

package/dist/web/hooks/openai-extensions.test.js

@@ -0,0 +1,114 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostAdaptor } from "../bridges/adaptor.js";
+import { McpAppBridge } from "../bridges/mcp-app/index.js";
+import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./test/utils.js";
+import { useDeepLink } from "./use-deep-link.js";
+import { useModelContext } from "./use-model-context.js";
+import { useViewState } from "./use-view-state.js";
+async function notifyHostContext(params) {
+    await act(async () => {
+        window.dispatchEvent(new MessageEvent("message", {
+            source: window.parent,
+            data: {
+                jsonrpc: "2.0",
+                method: "ui/notifications/host-context-changed",
+                params,
+            },
+        }));
+    });
+}
+describe("model context and deep links in the view", () => {
+    beforeEach(() => {
+        vi.stubGlobal("openai", undefined);
+        vi.stubGlobal("skybridge", {});
+        vi.stubGlobal("ResizeObserver", MockResizeObserver);
+        localStorage.clear();
+    });
+    afterEach(() => {
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        vi.unstubAllGlobals();
+        localStorage.clear();
+    });
+    it("merges model context with view state and drops it once the user removes it", async () => {
+        const postMessage = getMcpAppHostPostMessageMock({}, { hostCapabilities: { updateModelContext: {} } });
+        vi.stubGlobal("parent", { postMessage });
+        const { result } = renderHook(() => ({
+            model: useModelContext(),
+            view: useViewState({ tab: "a" }),
+        }));
+        await waitFor(() => expect(result.current.model.supported).toBe(true));
+        const content = [
+            {
+                type: "text",
+                text: "Selected ski",
+                _meta: { "openai/title": "Ski" },
+            },
+        ];
+        const lastModelContext = () => postMessage.mock.calls
+            .map(([message]) => message)
+            .filter((message) => message.method === "ui/update-model-context")
+            .at(-1)?.params;
+        await act(async () => result.current.model.update({
+            content,
+            structuredContent: { ski: 1, tab: "x" },
+        }));
+        await act(async () => result.current.view[1]({ tab: "b" }));
+        expect(lastModelContext()).toEqual({
+            structuredContent: { ski: 1, tab: "b" },
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ tab: "b" }),
+                    annotations: { audience: ["assistant"] },
+                },
+                ...content,
+            ],
+        });
+        await notifyHostContext({
+            "openai/modelContext": { updateId: "one", content },
+        });
+        expect(result.current.model.context).toEqual({ updateId: "one", content });
+        await notifyHostContext({ "openai/modelContext": null });
+        expect(result.current.model.context).toBeNull();
+        await act(async () => result.current.view[1]({ tab: "c" }));
+        expect(lastModelContext()).toEqual({
+            structuredContent: { tab: "c" },
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ tab: "c" }),
+                    annotations: { audience: ["assistant"] },
+                },
+            ],
+        });
+    });
+    it("rejects model context updates on hosts without the capability", async () => {
+        const postMessage = getMcpAppHostPostMessageMock();
+        vi.stubGlobal("parent", { postMessage });
+        const { result } = renderHook(useModelContext);
+        await expect(result.current.update({ content: [] })).rejects.toThrow("updateModelContext");
+        expect(result.current.supported).toBe(false);
+        expect(postMessage.mock.calls.some(([message]) => message.method === "ui/update-model-context")).toBe(false);
+    });
+    it("reads split legacy deep links and ignores malformed ones", async () => {
+        vi.stubGlobal("parent", {
+            postMessage: getMcpAppHostPostMessageMock({
+                "openai/deepLink": { url: "/parts?tag=bolt" },
+            }),
+        });
+        const { result } = renderHook(useDeepLink);
+        await waitFor(() => expect(result.current).toBe("/parts?tag=bolt"));
+        await notifyHostContext({
+            "openai/deepLink": {
+                path: ["parts", "a/b"],
+                query: [["tag", "hex bolt"]],
+            },
+        });
+        expect(result.current).toBe("/parts/a%2Fb?tag=hex+bolt");
+        await notifyHostContext({ "openai/deepLink": { url: "//evil.test" } });
+        expect(result.current).toBeUndefined();
+    });
+});
+//# sourceMappingURL=openai-extensions.test.js.map

package/dist/web/hooks/openai-extensions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-extensions.test.js","sourceRoot":"","sources":["../../../src/web/hooks/openai-extensions.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { act, renderHook, waitFor } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { HostAdaptor } from \"../bridges/adaptor.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/index.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useDeepLink } from \"./use-deep-link.js\";\nimport { useModelContext } from \"./use-model-context.js\";\nimport { useViewState } from \"./use-view-state.js\";\n\nasync function notifyHostContext(params: Record<string, unknown>) {\n  await act(async () => {\n    window.dispatchEvent(\n      new MessageEvent(\"message\", {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/host-context-changed\",\n          params,\n        },\n      }),\n    );\n  });\n}\n\ndescribe(\"model context and deep links in the view\", () => {\n  beforeEach(() => {\n    vi.stubGlobal(\"openai\", undefined);\n    vi.stubGlobal(\"skybridge\", {});\n    vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n    localStorage.clear();\n  });\n\n  afterEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    vi.unstubAllGlobals();\n    localStorage.clear();\n  });\n\n  it(\"merges model context with view state and drops it once the user removes it\", async () => {\n    const postMessage = getMcpAppHostPostMessageMock(\n      {},\n      { hostCapabilities: { updateModelContext: {} } },\n    );\n    vi.stubGlobal(\"parent\", { postMessage });\n    const { result } = renderHook(() => ({\n      model: useModelContext(),\n      view: useViewState({ tab: \"a\" }),\n    }));\n    await waitFor(() => expect(result.current.model.supported).toBe(true));\n    const content = [\n      {\n        type: \"text\" as const,\n        text: \"Selected ski\",\n        _meta: { \"openai/title\": \"Ski\" },\n      },\n    ];\n    const lastModelContext = () =>\n      postMessage.mock.calls\n        .map(([message]) => message as { method: string; params?: unknown })\n        .filter((message) => message.method === \"ui/update-model-context\")\n        .at(-1)?.params;\n\n    await act(async () =>\n      result.current.model.update({\n        content,\n        structuredContent: { ski: 1, tab: \"x\" },\n      }),\n    );\n    await act(async () => result.current.view[1]({ tab: \"b\" }));\n    expect(lastModelContext()).toEqual({\n      structuredContent: { ski: 1, tab: \"b\" },\n      content: [\n        {\n          type: \"text\",\n          text: JSON.stringify({ tab: \"b\" }),\n          annotations: { audience: [\"assistant\"] },\n        },\n        ...content,\n      ],\n    });\n\n    await notifyHostContext({\n      \"openai/modelContext\": { updateId: \"one\", content },\n    });\n    expect(result.current.model.context).toEqual({ updateId: \"one\", content });\n    await notifyHostContext({ \"openai/modelContext\": null });\n    expect(result.current.model.context).toBeNull();\n\n    await act(async () => result.current.view[1]({ tab: \"c\" }));\n    expect(lastModelContext()).toEqual({\n      structuredContent: { tab: \"c\" },\n      content: [\n        {\n          type: \"text\",\n          text: JSON.stringify({ tab: \"c\" }),\n          annotations: { audience: [\"assistant\"] },\n        },\n      ],\n    });\n  });\n\n  it(\"rejects model context updates on hosts without the capability\", async () => {\n    const postMessage = getMcpAppHostPostMessageMock();\n    vi.stubGlobal(\"parent\", { postMessage });\n    const { result } = renderHook(useModelContext);\n\n    await expect(result.current.update({ content: [] })).rejects.toThrow(\n      \"updateModelContext\",\n    );\n    expect(result.current.supported).toBe(false);\n    expect(\n      postMessage.mock.calls.some(\n        ([message]) => message.method === \"ui/update-model-context\",\n      ),\n    ).toBe(false);\n  });\n\n  it(\"reads split legacy deep links and ignores malformed ones\", async () => {\n    vi.stubGlobal(\"parent\", {\n      postMessage: getMcpAppHostPostMessageMock({\n        \"openai/deepLink\": { url: \"/parts?tag=bolt\" },\n      }),\n    });\n    const { result } = renderHook(useDeepLink);\n    await waitFor(() => expect(result.current).toBe(\"/parts?tag=bolt\"));\n\n    await notifyHostContext({\n      \"openai/deepLink\": {\n        path: [\"parts\", \"a/b\"],\n        query: [[\"tag\", \"hex bolt\"]],\n      },\n    });\n    expect(result.current).toBe(\"/parts/a%2Fb?tag=hex+bolt\");\n\n    await notifyHostContext({ \"openai/deepLink\": { url: \"//evil.test\" } });\n    expect(result.current).toBeUndefined();\n  });\n});\n"]}

package/dist/web/hooks/test/utils.d.ts

@@ -0,0 +1,21 @@
+import type { McpUiDownloadFileResult, McpUiHostCapabilities, McpUiHostContext, McpUiInitializeResult, McpUiToolResultNotification } from "@modelcontextprotocol/ext-apps";
+export declare class MockResizeObserver {
+    observe(): void;
+    unobserve(): void;
+    disconnect(): void;
+}
+export type McpAppHostMockOptions = {
+    hostCapabilities?: McpUiHostCapabilities;
+    downloadFileResult?: McpUiDownloadFileResult;
+    hostInfo?: McpUiInitializeResult["hostInfo"];
+};
+export declare const getMcpAppHostPostMessageMock: (initialContext?: McpUiHostContext, options?: McpAppHostMockOptions) => import("vitest").Mock<(message: {
+    method: string;
+    id: number;
+}) => void>;
+export declare const fireToolInputNotification: (args: Record<string, unknown>) => void;
+export declare const fireToolResultNotification: (params: {
+    content: McpUiToolResultNotification["params"]["content"];
+    structuredContent: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}) => void;

package/dist/web/hooks/test/utils.js

@@ -0,0 +1,75 @@
+import { fireEvent } from "@testing-library/react";
+import { act } from "react";
+import { vi } from "vitest";
+export class MockResizeObserver {
+    observe() { }
+    unobserve() { }
+    disconnect() { }
+}
+const DEFAULT_CONTEXT = {};
+export const getMcpAppHostPostMessageMock = (initialContext = DEFAULT_CONTEXT, options = {}) => vi.fn((message) => {
+    switch (message.method) {
+        case "ui/initialize": {
+            const result = {
+                protocolVersion: "2025-06-18",
+                hostInfo: options.hostInfo ?? { name: "test-host", version: "1.0.0" },
+                hostCapabilities: options.hostCapabilities ?? {},
+                hostContext: initialContext,
+            };
+            act(() => fireEvent(window, new MessageEvent("message", {
+                source: window.parent,
+                data: {
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    result,
+                },
+            })));
+            break;
+        }
+        case "ui/update-model-context": {
+            act(() => fireEvent(window, new MessageEvent("message", {
+                source: window.parent,
+                data: {
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    result: {},
+                },
+            })));
+            break;
+        }
+        case "ui/download-file": {
+            act(() => fireEvent(window, new MessageEvent("message", {
+                source: window.parent,
+                data: {
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    result: options.downloadFileResult ?? {},
+                },
+            })));
+            break;
+        }
+    }
+});
+export const fireToolInputNotification = (args) => {
+    fireEvent(window, new MessageEvent("message", {
+        source: window.parent,
+        data: {
+            jsonrpc: "2.0",
+            method: "ui/notifications/tool-input",
+            params: {
+                arguments: args,
+            },
+        },
+    }));
+};
+export const fireToolResultNotification = (params) => {
+    fireEvent(window, new MessageEvent("message", {
+        source: window.parent,
+        data: {
+            jsonrpc: "2.0",
+            method: "ui/notifications/tool-result",
+            params,
+        },
+    }));
+};
+//# sourceMappingURL=utils.js.map

package/dist/web/hooks/test/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/web/hooks/test/utils.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  McpUiDownloadFileResult,\n  McpUiHostCapabilities,\n  McpUiHostContext,\n  McpUiInitializeResult,\n  McpUiToolInputNotification,\n  McpUiToolResultNotification,\n} from \"@modelcontextprotocol/ext-apps\";\nimport { fireEvent } from \"@testing-library/react\";\nimport { act } from \"react\";\nimport { vi } from \"vitest\";\n\nexport class MockResizeObserver {\n  observe(): void {}\n  unobserve(): void {}\n  disconnect(): void {}\n}\n\nconst DEFAULT_CONTEXT: McpUiHostContext = {};\n\nexport type McpAppHostMockOptions = {\n  hostCapabilities?: McpUiHostCapabilities;\n  downloadFileResult?: McpUiDownloadFileResult;\n  hostInfo?: McpUiInitializeResult[\"hostInfo\"];\n};\n\nexport const getMcpAppHostPostMessageMock = (\n  initialContext: McpUiHostContext = DEFAULT_CONTEXT,\n  options: McpAppHostMockOptions = {},\n) =>\n  vi.fn((message: { method: string; id: number }) => {\n    switch (message.method) {\n      case \"ui/initialize\": {\n        const result: McpUiInitializeResult = {\n          protocolVersion: \"2025-06-18\",\n          hostInfo: options.hostInfo ?? { name: \"test-host\", version: \"1.0.0\" },\n          hostCapabilities: options.hostCapabilities ?? {},\n          hostContext: initialContext,\n        };\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{\n              jsonrpc: \"2.0\";\n              id: number;\n              result: McpUiInitializeResult;\n            }>(\"message\", {\n              source: window.parent,\n              data: {\n                jsonrpc: \"2.0\",\n                id: message.id,\n                result,\n              },\n            }),\n          ),\n        );\n        break;\n      }\n      case \"ui/update-model-context\": {\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{ jsonrpc: \"2.0\"; id: number; result: unknown }>(\n              \"message\",\n              {\n                source: window.parent,\n                data: {\n                  jsonrpc: \"2.0\",\n                  id: message.id,\n                  result: {},\n                },\n              },\n            ),\n          ),\n        );\n        break;\n      }\n      case \"ui/download-file\": {\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{\n              jsonrpc: \"2.0\";\n              id: number;\n              result: McpUiDownloadFileResult;\n            }>(\"message\", {\n              source: window.parent,\n              data: {\n                jsonrpc: \"2.0\",\n                id: message.id,\n                result: options.downloadFileResult ?? {},\n              },\n            }),\n          ),\n        );\n        break;\n      }\n    }\n  });\n\nexport const fireToolInputNotification = (args: Record<string, unknown>) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolInputNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-input\",\n          params: {\n            arguments: args,\n          },\n        },\n      },\n    ),\n  );\n};\n\nexport const fireToolResultNotification = (params: {\n  content: McpUiToolResultNotification[\"params\"][\"content\"];\n  structuredContent: Record<string, unknown>;\n  _meta?: Record<string, unknown>;\n}) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolResultNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-result\",\n          params,\n        },\n      },\n    ),\n  );\n};\n"]}

package/dist/{src/web → web}/hooks/use-call-tool.d.ts

@@ -1,4 +1,5 @@
-import type { CallToolArgs, CallToolResponse, HasRequiredKeys } from "../types.js";
+import { type CallToolArgs, type CallToolOptions, type CallToolResponse } from "../bridges/index.js";
+import type { HasRequiredKeys } from "../types.js";
 type CallToolIdleState = {
     status: "idle";
     isIdle: true;
@@ -35,13 +36,26 @@ type CallToolErrorState = {
     data: undefined;
     error: unknown;
 };
+/**
+ * State of a {@link useCallTool} invocation, discriminated by `status`.
+ * Use `isIdle` / `isPending` / `isSuccess` / `isError` for ergonomic conditional rendering.
+ */
 export type CallToolState<TData extends CallToolResponse = CallToolResponse> = CallToolIdleState | CallToolPendingState | CallToolSuccessState<TData> | CallToolErrorState;
+/**
+ * Optional callbacks fired around a {@link useCallTool} call.
+ * `onSettled` runs after success or error.
+ */
 export type SideEffects<ToolArgs, ToolResponse> = {
     onSuccess?: (data: ToolResponse, toolArgs: ToolArgs) => void;
     onError?: (error: unknown, toolArgs: ToolArgs) => void;
     onSettled?: (data: ToolResponse | undefined, error: unknown | undefined, toolArgs: ToolArgs) => void;
 };
 type IsArgsOptional<T> = [T] extends [null] ? true : HasRequiredKeys<T> extends false ? true : false;
+/**
+ * Fire-and-forget call function returned by {@link useCallTool}. Tracks state
+ * on the hook and supports optional {@link SideEffects} callbacks. Args are
+ * optional when the tool accepts none.
+ */
 export type CallToolFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ? {
     (): void;
     (sideEffects: SideEffects<TArgs, TResponse>): void;
@@ -51,12 +65,44 @@ export type CallToolFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ?
     (args: TArgs): void;
     (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;
 };
+/**
+ * Promise-returning call function returned by {@link useCallTool}. Rejects
+ * if the tool errors; use `try/catch` for error handling.
+ */
 export type CallToolAsyncFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ? {
     (): Promise<TResponse>;
     (args: TArgs): Promise<TResponse>;
 } : (args: TArgs) => Promise<TResponse>;
 type ToolResponseSignature = Pick<CallToolResponse, "structuredContent" | "meta">;
-export declare const useCallTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>>(name: string) => {
+/**
+ * Call a server tool from a view and track its execution state.
+ *
+ * Returns the current {@link CallToolState} plus two callers: `callTool`
+ * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`
+ * (promise-returning). If the same instance is invoked again while a call is
+ * in flight, the older response is dropped from the rendered state (but any
+ * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).
+ *
+ * Pair with {@link useToolInfo} to read the result of the tool invocation
+ * that produced the current view. For end-to-end type safety across tool
+ * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}
+ * over calling this hook directly.
+ *
+ * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).
+ * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.
+ *
+ * @example
+ * ```tsx
+ * const { callTool, isPending, data } = useCallTool<{ query: string }>("search");
+ *
+ * <button onClick={() => callTool({ query: "skybridge" }, {
+ *   onSuccess: (res) => console.log(res.structuredContent),
+ * })} />
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-call-tool
+ */
+export declare const useCallTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>>(name: string, options?: CallToolOptions) => {
     callTool: CallToolFn<ToolArgs, CallToolResponse & ToolResponse>;
     callToolAsync: CallToolAsyncFn<ToolArgs, CallToolResponse & ToolResponse>;
     status: "idle";

package/dist/web/hooks/use-call-tool.js

@@ -0,0 +1,101 @@
+import { useCallback, useRef, useState } from "react";
+import { getAdaptor, } from "../bridges/index.js";
+/**
+ * Call a server tool from a view and track its execution state.
+ *
+ * Returns the current {@link CallToolState} plus two callers: `callTool`
+ * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`
+ * (promise-returning). If the same instance is invoked again while a call is
+ * in flight, the older response is dropped from the rendered state (but any
+ * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).
+ *
+ * Pair with {@link useToolInfo} to read the result of the tool invocation
+ * that produced the current view. For end-to-end type safety across tool
+ * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}
+ * over calling this hook directly.
+ *
+ * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).
+ * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.
+ *
+ * @example
+ * ```tsx
+ * const { callTool, isPending, data } = useCallTool<{ query: string }>("search");
+ *
+ * <button onClick={() => callTool({ query: "skybridge" }, {
+ *   onSuccess: (res) => console.log(res.structuredContent),
+ * })} />
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-call-tool
+ */
+export const useCallTool = (name, options) => {
+    const [{ status, data, error }, setCallToolState] = useState({ status: "idle", data: undefined, error: undefined });
+    const callIdRef = useRef(0);
+    const adaptor = getAdaptor();
+    const timeout = options?.timeout;
+    const execute = useCallback(async (toolArgs) => {
+        const callId = ++callIdRef.current;
+        setCallToolState({
+            status: "pending",
+            data: undefined,
+            error: undefined,
+        });
+        try {
+            const data = await adaptor.callTool(name, toolArgs, ...(timeout === undefined ? [] : [{ timeout }]));
+            if (callId === callIdRef.current) {
+                setCallToolState({ status: "success", data, error: undefined });
+            }
+            return data;
+        }
+        catch (error) {
+            if (callId === callIdRef.current) {
+                setCallToolState({ status: "error", data: undefined, error });
+            }
+            throw error;
+        }
+    }, [adaptor, name, timeout]);
+    const callToolAsync = useCallback((toolArgs) => {
+        if (toolArgs === undefined) {
+            return execute(null);
+        }
+        return execute(toolArgs);
+    }, [execute]);
+    const callTool = useCallback((firstArg, sideEffects) => {
+        let toolArgs;
+        if (firstArg &&
+            typeof firstArg === "object" &&
+            ("onSuccess" in firstArg ||
+                "onError" in firstArg ||
+                "onSettled" in firstArg)) {
+            toolArgs = null; // no toolArgs provided
+            sideEffects = firstArg;
+        }
+        else {
+            toolArgs = (firstArg === undefined ? null : firstArg);
+        }
+        execute(toolArgs)
+            .then((data) => {
+            sideEffects?.onSuccess?.(data, toolArgs);
+            sideEffects?.onSettled?.(data, undefined, toolArgs);
+        })
+            .catch((error) => {
+            sideEffects?.onError?.(error, toolArgs);
+            sideEffects?.onSettled?.(undefined, error, toolArgs);
+        });
+    }, [execute]);
+    const callToolState = {
+        status,
+        data,
+        error,
+        isIdle: status === "idle",
+        isPending: status === "pending",
+        isSuccess: status === "success",
+        isError: status === "error",
+    };
+    return {
+        ...callToolState,
+        callTool,
+        callToolAsync,
+    };
+};
+//# sourceMappingURL=use-call-tool.js.map

package/dist/web/hooks/use-call-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-call-tool.js","sourceRoot":"","sources":["../../../src/web/hooks/use-call-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAIL,UAAU,GACX,MAAM,qBAAqB,CAAC;AA4G7B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAIzB,IAAY,EACZ,OAAyB,EACzB,EAAE;IAGF,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAK1D,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAEzD,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAEjC,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,QAAkB,EAAqC,EAAE;QAC9D,MAAM,MAAM,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC;QACnC,gBAAgB,CAAC;YACf,MAAM,EAAE,SAAS;YACjB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,CACjC,IAAI,EACJ,QAAQ,EACR,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAChD,CAAC;YACF,IAAI,MAAM,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YAChE,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,EACD,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CACzB,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAC/B,CAAC,QAAmB,EAAE,EAAE;QACtB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,IAAgB,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC,EACD,CAAC,OAAO,CAAC,CAC6C,CAAC;IAEzD,MAAM,QAAQ,GAAG,WAAW,CAC1B,CACE,QAAqE,EACrE,WAA6D,EAC7D,EAAE;QACF,IAAI,QAAkB,CAAC;QACvB,IACE,QAAQ;YACR,OAAO,QAAQ,KAAK,QAAQ;YAC5B,CAAC,WAAW,IAAI,QAAQ;gBACtB,SAAS,IAAI,QAAQ;gBACrB,WAAW,IAAI,QAAQ,CAAC,EAC1B,CAAC;YACD,QAAQ,GAAG,IAAgB,CAAC,CAAC,uBAAuB;YACpD,WAAW,GAAG,QAAQ,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAa,CAAC;QACpE,CAAC;QAED,OAAO,CAAC,QAAQ,CAAC;aACd,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,WAAW,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACzC,WAAW,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACtD,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,WAAW,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACxC,WAAW,EAAE,SAAS,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;IACP,CAAC,EACD,CAAC,OAAO,CAAC,CACwC,CAAC;IAEpD,MAAM,aAAa,GAAG;QACpB,MAAM;QACN,IAAI;QACJ,KAAK;QACL,MAAM,EAAE,MAAM,KAAK,MAAM;QACzB,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,OAAO,EAAE,MAAM,KAAK,OAAO;KACe,CAAC;IAE7C,OAAO;QACL,GAAG,aAAa;QAChB,QAAQ;QACR,aAAa;KACd,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { useCallback, useRef, useState } from \"react\";\n\nimport {\n  type CallToolArgs,\n  type CallToolOptions,\n  type CallToolResponse,\n  getAdaptor,\n} from \"../bridges/index.js\";\nimport type { HasRequiredKeys } from \"../types.js\";\n\ntype CallToolIdleState = {\n  status: \"idle\";\n  isIdle: true;\n  isPending: false;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolPendingState = {\n  status: \"pending\";\n  isIdle: false;\n  isPending: true;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolSuccessState<TData extends CallToolResponse = CallToolResponse> = {\n  status: \"success\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: true;\n  isError: false;\n  data: TData;\n  error: undefined;\n};\n\ntype CallToolErrorState = {\n  status: \"error\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: false;\n  isError: true;\n  data: undefined;\n  error: unknown;\n};\n\n/**\n * State of a {@link useCallTool} invocation, discriminated by `status`.\n * Use `isIdle` / `isPending` / `isSuccess` / `isError` for ergonomic conditional rendering.\n */\nexport type CallToolState<TData extends CallToolResponse = CallToolResponse> =\n  | CallToolIdleState\n  | CallToolPendingState\n  | CallToolSuccessState<TData>\n  | CallToolErrorState;\n\n/**\n * Optional callbacks fired around a {@link useCallTool} call.\n * `onSettled` runs after success or error.\n */\nexport type SideEffects<ToolArgs, ToolResponse> = {\n  onSuccess?: (data: ToolResponse, toolArgs: ToolArgs) => void;\n  onError?: (error: unknown, toolArgs: ToolArgs) => void;\n  onSettled?: (\n    data: ToolResponse | undefined,\n    error: unknown | undefined,\n    toolArgs: ToolArgs,\n  ) => void;\n};\n\ntype IsArgsOptional<T> = [T] extends [null]\n  ? true\n  : HasRequiredKeys<T> extends false\n    ? true\n    : false;\n\n/**\n * Fire-and-forget call function returned by {@link useCallTool}. Tracks state\n * on the hook and supports optional {@link SideEffects} callbacks. Args are\n * optional when the tool accepts none.\n */\nexport type CallToolFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): void;\n        (sideEffects: SideEffects<TArgs, TResponse>): void;\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      }\n    : {\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      };\n\n/**\n * Promise-returning call function returned by {@link useCallTool}. Rejects\n * if the tool errors; use `try/catch` for error handling.\n */\nexport type CallToolAsyncFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): Promise<TResponse>;\n        (args: TArgs): Promise<TResponse>;\n      }\n    : (args: TArgs) => Promise<TResponse>;\n\ntype ToolResponseSignature = Pick<\n  CallToolResponse,\n  \"structuredContent\" | \"meta\"\n>;\n\n/**\n * Call a server tool from a view and track its execution state.\n *\n * Returns the current {@link CallToolState} plus two callers: `callTool`\n * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`\n * (promise-returning). If the same instance is invoked again while a call is\n * in flight, the older response is dropped from the rendered state (but any\n * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).\n *\n * Pair with {@link useToolInfo} to read the result of the tool invocation\n * that produced the current view. For end-to-end type safety across tool\n * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}\n * over calling this hook directly.\n *\n * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).\n * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.\n *\n * @example\n * ```tsx\n * const { callTool, isPending, data } = useCallTool<{ query: string }>(\"search\");\n *\n * <button onClick={() => callTool({ query: \"skybridge\" }, {\n *   onSuccess: (res) => console.log(res.structuredContent),\n * })} />\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-call-tool\n */\nexport const useCallTool = <\n  ToolArgs extends CallToolArgs = null,\n  ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>,\n>(\n  name: string,\n  options?: CallToolOptions,\n) => {\n  type CombinedCallToolResponse = CallToolResponse & ToolResponse;\n\n  const [{ status, data, error }, setCallToolState] = useState<\n    Omit<\n      CallToolState<CombinedCallToolResponse>,\n      \"isIdle\" | \"isPending\" | \"isSuccess\" | \"isError\"\n    >\n  >({ status: \"idle\", data: undefined, error: undefined });\n\n  const callIdRef = useRef(0);\n  const adaptor = getAdaptor();\n  const timeout = options?.timeout;\n\n  const execute = useCallback(\n    async (toolArgs: ToolArgs): Promise<CombinedCallToolResponse> => {\n      const callId = ++callIdRef.current;\n      setCallToolState({\n        status: \"pending\",\n        data: undefined,\n        error: undefined,\n      });\n\n      try {\n        const data = await adaptor.callTool<ToolArgs, CombinedCallToolResponse>(\n          name,\n          toolArgs,\n          ...(timeout === undefined ? [] : [{ timeout }]),\n        );\n        if (callId === callIdRef.current) {\n          setCallToolState({ status: \"success\", data, error: undefined });\n        }\n\n        return data;\n      } catch (error) {\n        if (callId === callIdRef.current) {\n          setCallToolState({ status: \"error\", data: undefined, error });\n        }\n        throw error;\n      }\n    },\n    [adaptor, name, timeout],\n  );\n\n  const callToolAsync = useCallback(\n    (toolArgs?: ToolArgs) => {\n      if (toolArgs === undefined) {\n        return execute(null as ToolArgs);\n      }\n      return execute(toolArgs);\n    },\n    [execute],\n  ) as CallToolAsyncFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callTool = useCallback(\n    (\n      firstArg?: ToolArgs | SideEffects<ToolArgs, CombinedCallToolResponse>,\n      sideEffects?: SideEffects<ToolArgs, CombinedCallToolResponse>,\n    ) => {\n      let toolArgs: ToolArgs;\n      if (\n        firstArg &&\n        typeof firstArg === \"object\" &&\n        (\"onSuccess\" in firstArg ||\n          \"onError\" in firstArg ||\n          \"onSettled\" in firstArg)\n      ) {\n        toolArgs = null as ToolArgs; // no toolArgs provided\n        sideEffects = firstArg;\n      } else {\n        toolArgs = (firstArg === undefined ? null : firstArg) as ToolArgs;\n      }\n\n      execute(toolArgs)\n        .then((data) => {\n          sideEffects?.onSuccess?.(data, toolArgs);\n          sideEffects?.onSettled?.(data, undefined, toolArgs);\n        })\n        .catch((error) => {\n          sideEffects?.onError?.(error, toolArgs);\n          sideEffects?.onSettled?.(undefined, error, toolArgs);\n        });\n    },\n    [execute],\n  ) as CallToolFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callToolState = {\n    status,\n    data,\n    error,\n    isIdle: status === \"idle\",\n    isPending: status === \"pending\",\n    isSuccess: status === \"success\",\n    isError: status === \"error\",\n  } as CallToolState<CombinedCallToolResponse>;\n\n  return {\n    ...callToolState,\n    callTool,\n    callToolAsync,\n  };\n};\n"]}

package/dist/web/hooks/use-call-tool.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/web/hooks/use-call-tool.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-call-tool.test-d.js","sourceRoot":"","sources":["../../../src/web/hooks/use-call-tool.test-d.ts"],"names":[],"mappings":"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","sourcesContent":["import { expectTypeOf, test } from \"vitest\";\nimport type { CallToolResponse } from \"../bridges/types.js\";\nimport {\n  type CallToolState,\n  type SideEffects,\n  useCallTool,\n} from \"./use-call-tool.js\";\n\ntest(\"callTool can be called without args when ToolArgs is null\", () => {\n  const { callTool, callToolAsync } = useCallTool<null>(\"test-tool\");\n  callTool();\n  callTool({ onSuccess: () => {} });\n  callToolAsync();\n});\n\ntest(\"callTool requires args when ToolArgs has required properties\", () => {\n  type Args = { query: string };\n  const { callTool, callToolAsync } = useCallTool<Args>(\"test-tool\");\n\n  // @ts-expect-error - query is required\n  callTool();\n\n  callTool({ query: \"test\" });\n  callTool({ query: \"test\" }, { onSuccess: () => {} });\n\n  // @ts-expect-error - query is required\n  callToolAsync();\n  callToolAsync({ query: \"test\" });\n});\n\ntest(\"callTool supports sideEffects with correct types\", () => {\n  type Args = { id: number };\n  type Response = { structuredContent: { result: string } };\n\n  const { callTool } = useCallTool<Args, Response>(\"test-tool\");\n\n  callTool(\n    { id: 1 },\n    {\n      onSuccess: (data, args) => {\n        expectTypeOf(data.structuredContent.result).toBeString();\n        expectTypeOf(args.id).toBeNumber();\n      },\n      onError: (error, args) => {\n        expectTypeOf(error).toBeUnknown();\n        expectTypeOf(args.id).toBeNumber();\n      },\n      onSettled: (data, error, args) => {\n        if (data) {\n          expectTypeOf(data.structuredContent.result).toBeString();\n        }\n        expectTypeOf(error).toEqualTypeOf<unknown | undefined>();\n        expectTypeOf(args.id).toBeNumber();\n      },\n    },\n  );\n});\n\ntest(\"callTool allows sideEffects as first arg when ToolArgs is null\", () => {\n  type Response = { structuredContent: { value: number } };\n  const { callTool } = useCallTool<null, Response>(\"test-tool\");\n\n  callTool({\n    onSuccess: (data) => {\n      expectTypeOf(data.structuredContent.value).toBeNumber();\n    },\n  });\n});\n\ntest(\"callToolAsync returns correctly typed promise\", () => {\n  type Args = { name: string };\n  type Response = {\n    structuredContent: { greeting: string };\n    meta: { id: number };\n  };\n\n  const { callToolAsync } = useCallTool<Args, Response>(\"test-tool\");\n\n  const promise = callToolAsync({ name: \"test\" });\n\n  expectTypeOf(promise).resolves.toHaveProperty(\"structuredContent\");\n  expectTypeOf(promise).resolves.toHaveProperty(\"meta\");\n});\n\ntest(\"state narrowing works correctly with status\", () => {\n  type Response = { structuredContent: { data: string } };\n  const result = useCallTool<null, Response>(\"test-tool\");\n\n  if (result.status === \"idle\") {\n    expectTypeOf(result.isIdle).toEqualTypeOf<true>();\n    expectTypeOf(result.data).toEqualTypeOf<undefined>();\n  }\n\n  if (result.status === \"pending\") {\n    expectTypeOf(result.isPending).toEqualTypeOf<true>();\n    expectTypeOf(result.data).toEqualTypeOf<undefined>();\n  }\n\n  if (result.status === \"success\") {\n    expectTypeOf(result.isSuccess).toEqualTypeOf<true>();\n    expectTypeOf(result.data).not.toEqualTypeOf<undefined>();\n    expectTypeOf(result.data.structuredContent.data).toBeString();\n  }\n\n  if (result.status === \"error\") {\n    expectTypeOf(result.isError).toEqualTypeOf<true>();\n    expectTypeOf(result.error).toBeUnknown();\n  }\n});\n\ntest(\"state narrowing works correctly with boolean flags\", () => {\n  type Response = { structuredContent: { items: string[] } };\n  const result = useCallTool<null, Response>(\"test-tool\");\n\n  if (result.isIdle) {\n    expectTypeOf(result.status).toEqualTypeOf<\"idle\">();\n  }\n\n  if (result.isPending) {\n    expectTypeOf(result.status).toEqualTypeOf<\"pending\">();\n  }\n\n  if (result.isSuccess) {\n    expectTypeOf(result.status).toEqualTypeOf<\"success\">();\n    expectTypeOf(result.data.structuredContent.items).toBeArray();\n  }\n\n  if (result.isError) {\n    expectTypeOf(result.status).toEqualTypeOf<\"error\">();\n  }\n});\n\ntest(\"CallToolState type is correctly exported and usable\", () => {\n  type Response = { structuredContent: { foo: string } };\n  type MyState = CallToolState<CallToolResponse & Response>;\n\n  const state: MyState = {} as MyState;\n\n  if (state.status === \"success\") {\n    expectTypeOf(state.data.structuredContent.foo).toBeString();\n  }\n});\n\ntest(\"SideEffects type is correctly exported and usable\", () => {\n  type Args = { x: number };\n  type Response = CallToolResponse & { structuredContent: { y: string } };\n\n  const sideEffects: SideEffects<Args, Response> = {\n    onSuccess: (data, args) => {\n      expectTypeOf(data.structuredContent.y).toBeString();\n      expectTypeOf(args.x).toBeNumber();\n    },\n  };\n\n  expectTypeOf(sideEffects).toHaveProperty(\"onSuccess\");\n});\n"]}

package/dist/web/hooks/use-call-tool.test.d.ts

@@ -0,0 +1 @@
+export {};