@apollo/client-ai-apps 0.6.5 → 0.7.0

package/src/{mcp/react/hooks → react}/createHydrationUtils.ts

@@ -4,16 +4,14 @@ import type {
   OperationVariables,
   TypedDocumentNode,
 } from "@apollo/client";
-import { useApolloClient } from "./useApolloClient.js";
-import { useToolName } from "./useToolName.js";
-import { isReactive } from "../../../react/reactive.js";
-import type { Reactive } from "../../../react/reactive.js";
+import { useApolloClient } from "./hooks/internal/useApolloClient.js";
+import { isReactive, type Reactive } from "./reactive.js";
 import { equal } from "@wry/equality";
 import { __DEV__ } from "@apollo/client/utilities/environment";
 import {
   getToolNamesFromDocument,
   getVariableNamesFromDocument,
-} from "../../../utilities/index.js";
+} from "../utilities/index.js";
 
 type HydratedVariablesInput<TVariables> = {
   [K in keyof TVariables]: TVariables[K] | Reactive<TVariables[K]>;
@@ -48,13 +46,12 @@ export function createHydrationUtils<
     setVariables: SetVariables<StateVariables<TVariables, TInputVariables>>,
   ] {
     const client = useApolloClient();
-    const toolName = useToolName();
-    const [toolInput] = useState(() => client.toolInput);
+    const [toolInput] = useState(() => client["hydratedToolInput"]);
 
     const toolMatches =
       toolInput !== undefined &&
-      toolName !== undefined &&
-      documentToolNames.has(toolName);
+      client.toolInfo?.toolName !== undefined &&
+      documentToolNames.has(client.toolInfo.toolName);
 
     const [stateVars, setStateVars] = useState<Record<string, unknown>>(() => {
       const values: Record<string, unknown> = {};
@@ -125,7 +122,7 @@ export function createHydrationUtils<
     // present, so both paths are idempotent.
     useLayoutEffect(() => {
       if (toolMatches) {
-        client.clearToolInput();
+        client["clearHydratedToolInput"]();
       }
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);

package/src/react/hooks/__tests__/useApp.test.tsx

@@ -0,0 +1,46 @@
+import { test, expect } from "vitest";
+import {
+  disableActEnvironment,
+  renderHookToSnapshotStream,
+} from "@testing-library/react-render-stream";
+import { Suspense } from "react";
+import { InMemoryCache } from "@apollo/client";
+import { App } from "@modelcontextprotocol/ext-apps";
+
+import { useApp } from "../useApp.js";
+import {
+  eachHostEnv,
+  mockApplicationManifest,
+  spyOnConsole,
+} from "../../../testing/internal/index.js";
+import { ApolloProvider } from "../../ApolloProvider.js";
+
+eachHostEnv((setupHost, ApolloClient) => {
+  test("returns app instance created by ApolloClient", async () => {
+    using _ = spyOnConsole("debug");
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+
+    using env = await setupHost({
+      client,
+      toolCall: { name: "Test", result: { structuredContent: {} } },
+    });
+    const { host, params } = env;
+
+    host.sendToolInput(params.toolInput);
+    host.sendToolResult(params.toolResult);
+
+    using _disabledAct = disableActEnvironment();
+    const { takeSnapshot } = await renderHookToSnapshotStream(() => useApp(), {
+      wrapper: ({ children }) => (
+        <Suspense>
+          <ApolloProvider client={client}>{children}</ApolloProvider>
+        </Suspense>
+      ),
+    });
+
+    await expect(takeSnapshot()).resolves.toBeInstanceOf(App);
+  });
+});

package/src/react/hooks/__tests__/useHostContext.test.tsx

@@ -0,0 +1,99 @@
+import { expect, test } from "vitest";
+import { InMemoryCache } from "@apollo/client";
+import {
+  eachHostEnv,
+  minimalHostContextWithToolName,
+  mockApplicationManifest,
+  spyOnConsole,
+} from "../../../testing/internal/index.js";
+import {
+  disableActEnvironment,
+  renderHookToSnapshotStream,
+} from "@testing-library/react-render-stream";
+import { useHostContext } from "../useHostContext.js";
+import { ApolloProvider } from "../../ApolloProvider.js";
+
+eachHostEnv((setupHost, ApolloClient) => {
+  test("returns the host context from the host", async () => {
+    using _ = spyOnConsole("debug");
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+
+    using env = await setupHost({
+      client,
+      toolCall: {
+        name: "GetProduct",
+        result: { structuredContent: { result: { data: { product: null } } } },
+      },
+      hostContext: { theme: "light" },
+    });
+    const { host, params } = env;
+
+    host.sendToolInput(params.toolInput);
+    host.sendToolResult(params.toolResult);
+
+    using _disabledAct = disableActEnvironment();
+    const { takeSnapshot } = await renderHookToSnapshotStream(
+      () => useHostContext(),
+      {
+        wrapper: ({ children }) => (
+          <ApolloProvider client={client}>{children}</ApolloProvider>
+        ),
+      }
+    );
+
+    await expect(takeSnapshot()).resolves.toStrictEqual({
+      ...minimalHostContextWithToolName("GetProduct"),
+      theme: "light",
+    });
+
+    await expect(takeSnapshot).not.toRerender();
+  });
+
+  test("rerenders when the host context changes", async () => {
+    using _ = spyOnConsole("debug");
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+
+    using env = await setupHost({
+      client,
+      toolCall: {
+        name: "GetProduct",
+        result: { structuredContent: { result: { data: { product: null } } } },
+      },
+      hostContext: { theme: "light" },
+    });
+    const { host, params } = env;
+
+    host.sendToolInput(params.toolInput);
+    host.sendToolResult(params.toolResult);
+
+    using _disabledAct = disableActEnvironment();
+    const { takeSnapshot } = await renderHookToSnapshotStream(
+      () => useHostContext(),
+      {
+        wrapper: ({ children }) => (
+          <ApolloProvider client={client}>{children}</ApolloProvider>
+        ),
+      }
+    );
+
+    await expect(takeSnapshot()).resolves.toStrictEqual({
+      ...minimalHostContextWithToolName("GetProduct"),
+      theme: "light",
+    });
+
+    host.sendHostContextChanged({ theme: "dark" });
+
+    await expect(takeSnapshot()).resolves.toStrictEqual({
+      ...minimalHostContextWithToolName("GetProduct"),
+      theme: "dark",
+    });
+
+    await expect(takeSnapshot).not.toRerender();
+  });
+});

package/src/react/hooks/__tests__/useToolInfo.test.tsx

@@ -0,0 +1,98 @@
+import { test, expect } from "vitest";
+import {
+  disableActEnvironment,
+  renderHookToSnapshotStream,
+} from "@testing-library/react-render-stream";
+import { Suspense } from "react";
+import { InMemoryCache } from "@apollo/client";
+
+import { useToolInfo } from "../useToolInfo.js";
+import {
+  eachHostEnv,
+  mockApplicationManifest,
+  spyOnConsole,
+} from "../../../testing/internal/index.js";
+import { ApolloProvider } from "../../ApolloProvider.js";
+
+eachHostEnv((setupHost, ApolloClient, { hostEnv }) => {
+  test("returns tool name and input combined", async () => {
+    using _ = spyOnConsole("debug");
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+
+    using env = await setupHost({
+      client,
+      toolCall: {
+        name: "GetProduct",
+        input: { id: "1" },
+        result: { structuredContent: { result: { data: { product: null } } } },
+      },
+    });
+    const { host, params } = env;
+
+    host.sendToolInput(params.toolInput);
+    host.sendToolResult(params.toolResult);
+
+    using _disabledAct = disableActEnvironment();
+    const { takeSnapshot } = await renderHookToSnapshotStream(
+      () => useToolInfo(),
+      {
+        wrapper: ({ children }) => (
+          <Suspense>
+            <ApolloProvider client={client}>{children}</ApolloProvider>
+          </Suspense>
+        ),
+      }
+    );
+
+    await expect(takeSnapshot()).resolves.toEqual({
+      toolName: "GetProduct",
+      toolInput: { id: "1" },
+    });
+
+    await expect(takeSnapshot).not.toRerender();
+  });
+
+  if (hostEnv === "openai") {
+    test("returns undefined toolInput when toolInput is not provided", async () => {
+      using _ = spyOnConsole("debug");
+      const client = new ApolloClient({
+        cache: new InMemoryCache(),
+        manifest: mockApplicationManifest(),
+      });
+
+      using env = await setupHost({
+        client,
+        toolCall: {
+          name: "GetProduct",
+          result: {
+            structuredContent: { result: { data: { product: null } } },
+          },
+        },
+      });
+      const { host, params } = env;
+
+      host.sendToolResult(params.toolResult);
+
+      using _disabledAct = disableActEnvironment();
+      const { takeSnapshot } = await renderHookToSnapshotStream(
+        () => useToolInfo(),
+        {
+          wrapper: ({ children }) => (
+            <Suspense>
+              <ApolloProvider client={client}>{children}</ApolloProvider>
+            </Suspense>
+          ),
+        }
+      );
+
+      await expect(takeSnapshot()).resolves.toEqual({
+        toolName: "GetProduct",
+        toolInput: undefined,
+      });
+      await expect(takeSnapshot).not.toRerender();
+    });
+  }
+});

package/src/react/hooks/__tests__/useToolMetadata.test.tsx

@@ -0,0 +1,58 @@
+import { test, expect } from "vitest";
+import {
+  disableActEnvironment,
+  renderHookToSnapshotStream,
+} from "@testing-library/react-render-stream";
+import { Suspense } from "react";
+import { InMemoryCache } from "@apollo/client";
+import { useToolMetadata } from "../useToolMetadata.js";
+import {
+  eachHostEnv,
+  mockApplicationManifest,
+  spyOnConsole,
+} from "../../../testing/internal/index.js";
+import { ApolloProvider } from "../../ApolloProvider.js";
+
+eachHostEnv((setupHost, ApolloClient) => {
+  test("returns the tool metadata from the MCP host", async () => {
+    using _ = spyOnConsole("debug");
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+
+    using env = await setupHost({
+      client,
+      toolCall: {
+        name: "TestTool",
+        result: {
+          structuredContent: {},
+          _meta: { customField: "customValue" },
+        },
+      },
+    });
+    const { host, params } = env;
+
+    host.sendToolInput(params.toolInput);
+    host.sendToolResult(params.toolResult);
+
+    using _disabledAct = disableActEnvironment();
+    const { takeSnapshot } = await renderHookToSnapshotStream(
+      () => useToolMetadata(),
+      {
+        wrapper: ({ children }) => (
+          <Suspense>
+            <ApolloProvider client={client}>{children}</ApolloProvider>
+          </Suspense>
+        ),
+      }
+    );
+
+    await expect(takeSnapshot()).resolves.toEqual({
+      toolName: "TestTool",
+      customField: "customValue",
+    });
+
+    await expect(takeSnapshot).not.toRerender();
+  });
+});

package/src/{mcp/react/hooks → react/hooks/internal}/useApolloClient.ts

@@ -1,9 +1,9 @@
 import { useApolloClient as useBaseApolloClient } from "@apollo/client/react";
-import { ApolloClient } from "../../core/ApolloClient.js";
+import { AbstractApolloClient } from "../../../core/AbstractApolloClient.js";
 import { aiClientSymbol, invariant } from "../../../utilities/index.js";
 
-export function useApolloClient(override?: ApolloClient) {
-  const client = useBaseApolloClient(override) as ApolloClient;
+export function useApolloClient() {
+  const client = useBaseApolloClient() as AbstractApolloClient;
 
   invariant(
     client[aiClientSymbol],

package/src/{mcp/react → react}/hooks/useApp.ts

@@ -1,4 +1,4 @@
-import { useApolloClient } from "./useApolloClient.js";
+import { useApolloClient } from "./internal/useApolloClient.js";
 
 export function useApp() {
   return useApolloClient()["appManager"].app;

package/src/{openai/react → react}/hooks/useHostContext.ts

@@ -1,5 +1,5 @@
 import { useCallback, useSyncExternalStore } from "react";
-import { useApolloClient } from "./useApolloClient";
+import { useApolloClient } from "./internal/useApolloClient";
 
 export function useHostContext() {
   const appManager = useApolloClient()["appManager"];

package/src/react/hooks/useToolInfo.ts

@@ -0,0 +1,6 @@
+import type { ToolInfo } from "../../core/typeRegistration.js";
+import { useApolloClient } from "./internal/useApolloClient.js";
+
+export function useToolInfo(): ToolInfo | undefined {
+  return useApolloClient().toolInfo;
+}

package/src/react/hooks/useToolMetadata.ts

@@ -0,0 +1,5 @@
+import { useApolloClient } from "./internal/useApolloClient.js";
+
+export function useToolMetadata() {
+  return useApolloClient().toolMetadata;
+}

package/src/react/index.ts

@@ -1,40 +1,9 @@
-import { missingHook } from "./missingHook.js";
-
 export { ApolloProvider } from "./ApolloProvider.js";
 export { reactive } from "./reactive.js";
 export type { Reactive } from "./reactive.js";
 
-// Use `mcp` related types since these are the most common between the two
-// targets
-export const useApp =
-  missingHook<typeof import("./index.mcp.js").useApp>("useApp");
-
-export const useHostContext =
-  missingHook<typeof import("./index.mcp.js").useHostContext>("useHostContext");
-
-/**
- * @deprecated Please use the `useToolInfo` hook. `useToolInput` will be removed
- * in the next major version.
- */
-export const useToolInput =
-  missingHook<typeof import("./index.mcp.js").useToolInput>("useToolInput");
-
-export const useToolMetadata =
-  missingHook<typeof import("./index.mcp.js").useToolMetadata>(
-    "useToolMetadata"
-  );
-
-/**
- * @deprecated Please use the `useToolInfo` hook. `useToolName` will be removed
- * in the next major version.
- */
-export const useToolName =
-  missingHook<typeof import("./index.mcp.js").useToolName>("useToolName");
-
-export const useToolInfo =
-  missingHook<typeof import("./index.mcp.js").useToolInfo>("useToolInfo");
-
-/** @experimental */
-export const createHydrationUtils = missingHook<
-  typeof import("./index.mcp.js").createHydrationUtils
->("createHydrationUtils");
+export { useApp } from "./hooks/useApp.js";
+export { useHostContext } from "./hooks/useHostContext.js";
+export { useToolInfo } from "./hooks/useToolInfo.js";
+export { useToolMetadata } from "./hooks/useToolMetadata.js";
+export { createHydrationUtils } from "./createHydrationUtils.js";

package/src/testing/internal/graphql/parseManifestOperation.ts

@@ -0,0 +1,87 @@
+import {
+  Kind,
+  print,
+  visit,
+  type DirectiveNode,
+  type DocumentNode,
+  type OperationDefinitionNode,
+} from "graphql";
+import type {
+  ManifestOperation,
+  ManifestTool,
+} from "../../../types/application-manifest";
+import {
+  getOperationDefinition,
+  removeDirectivesFromDocument,
+} from "@apollo/client/utilities/internal";
+import * as crypto from "node:crypto";
+import {
+  getDirectiveArgument,
+  getTypeName,
+  maybeGetArgumentValue,
+} from "../../../vite/utilities/graphql.js";
+import { invariant } from "../../../utilities/index.js";
+
+export function parseManifestOperation(
+  document: DocumentNode
+): ManifestOperation {
+  const operation = getOperationDefinition(document);
+  invariant(operation, "Must provide an operation to the document");
+
+  const variables: ManifestOperation["variables"] = {};
+  const tools: ManifestTool[] = [];
+  let prefetch = false;
+
+  const modified = removeDirectivesFromDocument(
+    [{ name: "prefetch" }, { name: "tool" }],
+    visit(document, {
+      Directive(node) {
+        if (node.name.value === "tool") {
+          tools.push(parseToolDefinition(node, operation));
+        }
+        prefetch ||= node.name.value === "prefetch";
+      },
+      VariableDefinition(node) {
+        variables[node.variable.name.value] = getTypeName(node.type);
+      },
+    })
+  )!;
+
+  const body = print(modified);
+  const hash = crypto.createHash("sha256").update(body).digest("hex");
+
+  const manifestOperation: ManifestOperation = {
+    id: hash,
+    name: operation.name!.value,
+    body,
+    type: operation.operation as "query" | "mutation",
+    prefetch,
+    variables,
+    tools,
+  };
+
+  if (prefetch) {
+    manifestOperation.prefetchID = "__anonymous";
+  }
+
+  return manifestOperation;
+}
+
+function parseToolDefinition(
+  directive: DirectiveNode,
+  operation: OperationDefinitionNode
+): ManifestTool {
+  const nameArg = maybeGetArgumentValue(
+    getDirectiveArgument("name", directive),
+    Kind.STRING
+  );
+  const descriptionArg = maybeGetArgumentValue(
+    getDirectiveArgument("description", directive),
+    Kind.STRING
+  );
+
+  return {
+    name: nameArg ?? operation.name!.value,
+    description: descriptionArg ?? operation.description!.value,
+  };
+}

package/src/testing/internal/index.ts

@@ -1,10 +1,13 @@
+export { createHostEnv } from "./utilities/createHostEnv.js";
 export { dispatchStateChange } from "./openai/dispatchStateChange.js";
+export { eachHostEnv } from "./tests/eachHostEnv.js";
 export { graphqlToolResult } from "./mcp/graphqlToolResult.js";
 export { mockApplicationManifest } from "./utilities/mockApplicationManifest.js";
 export { stubOpenAiGlobals } from "./openai/stubOpenAiGlobals.js";
 export { minimalHostContextWithToolName } from "./mcp/minimalHostContextWithToolName.js";
 export { mockMcpHost } from "./mcp/mockMcpHost.js";
 export { ObservableStream } from "./utilities/ObservableStream.js";
+export { parseManifestOperation } from "./graphql/parseManifestOperation.js";
 export { renderAsync } from "./react/renderAsync.js";
 export { spyOnConsole } from "./utilities/spyOnConsole.js";
 export { wait } from "./utilities/wait.js";

package/src/testing/internal/matchers/index.ts

@@ -1,3 +1,4 @@
 import "./toComplete.js";
+import "./toEmitAnything.js";
 import "./toEmitValue.js";
 import "./toRerender.js";

package/src/testing/internal/matchers/toEmitAnything.ts

@@ -0,0 +1,43 @@
+import { expect } from "vitest";
+import type {
+  ObservableStream,
+  TakeOptions,
+} from "../utilities/ObservableStream";
+
+expect.extend({
+  async toEmitAnything(actual, options: TakeOptions) {
+    const stream = actual as ObservableStream<any>;
+    const hint = this.utils.matcherHint("toEmitAnything", "stream", "", {
+      isNot: this.isNot,
+    });
+
+    try {
+      const value = await stream.peek(options);
+
+      return {
+        pass: true,
+        message: () => {
+          return (
+            hint +
+            "\n\nExpected stream not to emit anything but it did." +
+            "\n\nReceived:\n" +
+            this.utils.printReceived(value)
+          );
+        },
+      };
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.message === "Timeout waiting for next event"
+      ) {
+        return {
+          pass: false,
+          message: () =>
+            hint + "\n\nExpected stream to emit an event but it did not.",
+        };
+      } else {
+        throw error;
+      }
+    }
+  },
+});

package/src/testing/internal/matchers/types.ts

@@ -5,6 +5,7 @@ interface CustomMatchers<R = unknown> {
   toRerender: (options?: NextRenderOptions) => Promise<R>;
   toComplete: (options?: TakeOptions) => Promise<R>;
   toEmitValue: (expected: unknown, options?: TakeOptions) => Promise<R>;
+  toEmitAnything: (options?: TakeOptions) => Promise<R>;
 }
 
 declare module "vitest" {

package/src/testing/internal/mcp/mockMcpHost.ts

@@ -14,14 +14,16 @@ import type {
 import { invariant, promiseWithResolvers } from "../../../utilities/index.js";
 
 export interface MockMcpHost extends Disposable {
-  sendToolResult(params: McpUiToolResultNotification["params"]): Promise<void>;
+  sendToolResult(
+    params: Partial<McpUiToolResultNotification["params"]>
+  ): Promise<void>;
   sendToolInput(params: McpUiToolInputNotification["params"]): Promise<void>;
   sendHostContextChanged(
     params: McpUiHostContextChangedNotification["params"]
   ): Promise<void>;
   mockToolCall(
     name: string,
-    handler: (params: CallToolRequest["params"]) => CallToolResult
+    handler: (params: CallToolRequest["params"]) => Partial<CallToolResult>
   ): () => void;
   /**
    * Register an MCP App to be closed during cleanup. This prevents the App's
@@ -100,7 +102,7 @@ export async function mockMcpHost(
   const cleanupFns = new Set<() => void>();
   const toolCallHandlers = new Map<
     string,
-    (params: CallToolRequest["params"]) => CallToolResult
+    (params: CallToolRequest["params"]) => Partial<CallToolResult>
   >();
 
   const listener = (event: MessageEvent<unknown>) => {
@@ -137,10 +139,20 @@ export async function mockMcpHost(
         `mockMcpHost: A mock tool call handler for '${params.name}' is not registered.`
       );
 
+      const result = handler(params);
+
+      if (result.structuredContent && !result.content) {
+        result.content = [
+          { type: "text", text: JSON.stringify(result.structuredContent) },
+        ];
+      }
+
+      result.content ||= [];
+
       window.postMessage({
         jsonrpc: "2.0",
         id: data.id,
-        result: handler(params),
+        result,
       });
     }
   };
@@ -156,6 +168,15 @@ export async function mockMcpHost(
   return {
     async sendToolResult(params) {
       await initialized;
+
+      if (params.structuredContent && !params.content) {
+        params.content = [
+          { type: "text", text: JSON.stringify(params.structuredContent) },
+        ];
+      }
+
+      params.content ||= [];
+
       window.postMessage({
         jsonrpc: "2.0",
         method: "ui/notifications/tool-result",