@copilotkit/react-native 1.70.3 → 1.71.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/USAGE.md +76 -5
  2. package/dist/headless.cjs +1 -1
  3. package/dist/headless.d.cts +59 -3
  4. package/dist/headless.d.mts +59 -3
  5. package/dist/headless.mjs +1 -1
  6. package/dist/index.cjs +1 -1
  7. package/dist/index.d.cts +3 -3
  8. package/dist/index.d.mts +3 -3
  9. package/dist/index.mjs +1 -1
  10. package/dist/useRenderTool-DFz206nL.d.cts +149 -0
  11. package/dist/useRenderTool-DsCxzyAP.d.mts +149 -0
  12. package/dist/useRenderTool-L3Rw6SYD.cjs +298 -0
  13. package/dist/useRenderTool-L3Rw6SYD.cjs.map +1 -0
  14. package/dist/useRenderTool-pLM3upcs.mjs +285 -0
  15. package/dist/useRenderTool-pLM3upcs.mjs.map +1 -0
  16. package/package.json +4 -4
  17. package/src/__mocks__/test-copilotkit.tsx +14 -2
  18. package/src/__tests__/frontend-tool-render.test-d.tsx +148 -0
  19. package/src/__tests__/headless-entry-surface.test.ts +232 -2
  20. package/src/__tests__/headless-value-exports.test.ts +16 -5
  21. package/src/components/__tests__/CopilotChatToolCalls.test.tsx +26 -22
  22. package/src/headless.ts +79 -7
  23. package/src/hooks/__tests__/render-tool-call.integration.test.tsx +17 -15
  24. package/src/hooks/__tests__/useRenderTool.test.tsx +733 -202
  25. package/src/hooks/useRenderTool.ts +482 -49
  26. package/dist/useRenderTool-BBxnOOeJ.d.mts +0 -161
  27. package/dist/useRenderTool-BWo11PCL.d.cts +0 -161
  28. package/dist/useRenderTool-CKEPq7MQ.cjs +0 -162
  29. package/dist/useRenderTool-CKEPq7MQ.cjs.map +0 -1
  30. package/dist/useRenderTool-l7M-I8rT.mjs +0 -149
  31. package/dist/useRenderTool-l7M-I8rT.mjs.map +0 -1
  32. package/src/hooks/index.ts +0 -3
  33. package/src/hooks/render-tool-types.ts +0 -55
@@ -34,40 +34,44 @@ vi.mock("react-native", async () => {
34
34
  });
35
35
 
36
36
  import { CopilotChat } from "../CopilotChat";
37
- import { useRenderTool } from "../../hooks/useRenderTool";
37
+ import { useRenderTool } from "../../headless";
38
38
  import { TestCopilotKit } from "../../__mocks__/test-copilotkit";
39
39
  import { assistantToolCall, toolMessage } from "../../__mocks__/tool-fixtures";
40
40
 
41
- // Reports status + args only. Assertions about the RESULT must NOT use this one:
42
- // its output cannot distinguish "the correlated result reached the renderer" from
43
- // "status flipped for some other reason", which is how a corrupted tool-message
44
- // content passed unnoticed. Use `ReportRegistrar` below for those.
41
+ // Every registrar in this file uses `useRenderTool`, i.e. react-core's
42
+ // RENDERER-ONLY hook (RN re-exports it and owns no hook of its own). None of them
43
+ // registers a callable tool, which is exactly right here: the chat's job is to
44
+ // paint a tool call, and whether the tool is the frontend's or the server's makes
45
+ // no difference to that.
46
+ //
47
+ // Reports status + parameters only. Assertions about the RESULT must NOT use this
48
+ // one: its output cannot distinguish "the correlated result reached the renderer"
49
+ // from "status flipped for some other reason", which is how a corrupted
50
+ // tool-message content passed unnoticed. Use `ReportRegistrar` below for those.
45
51
  function Registrar() {
46
52
  useRenderTool({
47
53
  name: "showPlaces",
48
- description: "Show places",
49
54
  parameters: z.object({ title: z.string() }),
50
- // Tolerates partial props — that is the contract while streaming.
51
- render: ({ args, status }) => (
52
- <div data-testid="places">{`${status}:${(args as { title?: string }).title ?? ""}`}</div>
55
+ // Tolerates partial parameters — that is the contract while streaming.
56
+ render: ({ parameters, status }) => (
57
+ <div data-testid="places">{`${status}:${parameters.title ?? ""}`}</div>
53
58
  ),
54
59
  });
55
60
  return null;
56
61
  }
57
62
 
58
- // Reports status, args AND result together, so one assertion observes the whole
59
- // output of the `toolCallId -> ToolMessage` correlation: the status it derived,
60
- // the args it parsed, and the result content it actually handed the renderer.
61
- // `undefined` is spelled out rather than stringified, so an absent result stays
62
- // distinguishable from an empty-string one.
63
+ // Reports status, parameters AND result together, so one assertion observes the
64
+ // whole output of the `toolCallId -> ToolMessage` correlation: the status it
65
+ // derived, the parameters it parsed, and the result content it actually handed
66
+ // the renderer. `undefined` is spelled out rather than stringified, so an absent
67
+ // result stays distinguishable from an empty-string one.
63
68
  function ReportRegistrar() {
64
69
  useRenderTool({
65
70
  name: "reportPlaces",
66
- description: "Report places",
67
71
  parameters: z.object({ title: z.string() }),
68
- render: ({ args, status, result }) => (
72
+ render: ({ parameters, status, result }) => (
69
73
  <div data-testid="report">
70
- {`${status}:${(args as { title?: string }).title ?? ""}|${
74
+ {`${status}:${parameters.title ?? ""}|${
71
75
  result === undefined ? "<no result>" : result
72
76
  }`}
73
77
  </div>
@@ -76,14 +80,15 @@ function ReportRegistrar() {
76
80
  return null;
77
81
  }
78
82
 
79
- // Renders the raw args object it receives, so tests can assert exactly what the
80
- // renderer got for degenerate argument strings (empty / unparseable).
83
+ // Renders the raw parameters object it receives, so tests can assert exactly what
84
+ // the renderer got for degenerate argument strings (empty / unparseable).
81
85
  function ArgsRegistrar() {
82
86
  useRenderTool({
83
87
  name: "echoArgs",
84
- description: "Echo args",
85
88
  parameters: z.object({}),
86
- render: ({ args }) => <div data-testid="args">{JSON.stringify(args)}</div>,
89
+ render: ({ parameters }) => (
90
+ <div data-testid="args">{JSON.stringify(parameters)}</div>
91
+ ),
87
92
  });
88
93
  return null;
89
94
  }
@@ -94,7 +99,6 @@ function ArgsRegistrar() {
94
99
  function ResultRegistrar() {
95
100
  useRenderTool({
96
101
  name: "echoResult",
97
- description: "Echo result",
98
102
  parameters: z.object({}),
99
103
  render: ({ status, result }) => (
100
104
  <div data-testid="result">{`${status}|${String(result)}`}</div>
package/src/headless.ts CHANGED
@@ -28,6 +28,10 @@
28
28
  // Must run before any CopilotKit code that relies on ReadableStream / fetch streaming.
29
29
  import "./polyfills";
30
30
 
31
+ // Type-only, so both are erased and neither can run before the polyfills above.
32
+ import type React from "react";
33
+ import type { ReactToolCallRenderer } from "@copilotkit/react-core/v2/headless";
34
+
31
35
  // React Native provider (no web deps, no bottom-sheet, no expo native modules)
32
36
  export { CopilotKitProvider } from "./CopilotKitProvider";
33
37
  export type { CopilotKitNativeProviderProps } from "./CopilotKitProvider";
@@ -115,14 +119,26 @@ export type {
115
119
  AgentCapabilities,
116
120
  } from "@ag-ui/client";
117
121
 
118
- // Render tool registration (React Native flavour: RN-typed render function,
119
- // registered into react-core's canonical registry — no local registry).
122
+ // Render tool registration. `useRenderTool` is a TEMPORARY, deprecated
123
+ // COMPATIBILITY SHIM over BOTH core hooks — routing rules and reasoning in
124
+ // src/hooks/useRenderTool.ts — scheduled for removal in the next minor (tracked
125
+ // in CopilotKit/CopilotKit#6976, Linear OSS-1148), after
126
+ // which this line goes back to a plain re-export from
127
+ // @copilotkit/react-core/v2/headless. Contract and migration notes:
128
+ // /reference/react-native/hooks/useRenderTool.
129
+ //
130
+ // DO NOT reintroduce a LOCAL hook under either name. RN's old `useRenderTool`
131
+ // forwarded its whole body to `useFrontendTool` — core's OTHER hook, wearing
132
+ // this one's name — so `name: "*"` registered a frontend tool literally called
133
+ // `*`. Core never advertised it (`buildFrontendTools` filters that name out),
134
+ // but `*` IS core's catch-all handler name: a display-only wildcard therefore
135
+ // auto-answered every otherwise-unanswered tool call with an empty tool result
136
+ // and asked for a follow-up turn. The shim registers nothing itself: every
137
+ // path delegates to a react-core hook, and
138
+ // src/__tests__/headless-entry-surface.test.ts fails the build if any module in
139
+ // this entry's graph grows a registry of its own.
120
140
  export { useRenderTool } from "./hooks/useRenderTool";
121
- export type { UseRenderToolOptions } from "./hooks/useRenderTool";
122
- export type {
123
- RenderToolProps,
124
- RenderToolFunction,
125
- } from "./hooks/render-tool-types";
141
+ export type { RenderToolProps } from "@copilotkit/react-core/v2/headless";
126
142
 
127
143
  // Render tool consumption. react-core's hook is platform-agnostic — it pulls no
128
144
  // DOM and no chat-UI stack, and it returns ReactElement | null, which is exactly
@@ -130,3 +146,59 @@ export type {
130
146
  // on any surface, chat or not.
131
147
  export { useRenderToolCall } from "@copilotkit/react-core/v2/headless";
132
148
  export type { ReactToolCallRenderer } from "@copilotkit/react-core/v2/headless";
149
+
150
+ /**
151
+ * A tool-call render function whose return type is narrowed to React Native's
152
+ * `ReactElement | null`. Annotate a `useFrontendTool` renderer with it to have
153
+ * the compiler reject a return React Native cannot draw.
154
+ *
155
+ * `useFrontendTool`'s `render` is `ReactToolCallRenderer<T>["render"]`, i.e. a
156
+ * `React.ComponentType`, so it returns `ReactNode` — which means
157
+ * `render: ({ args }) => \`Weather in ${args.city}\`` typechecks and then throws
158
+ * *Text strings must be rendered within a `<Text>` component* on a device. This
159
+ * type is what rejects it at `check-types` instead. (core's `useRenderTool`
160
+ * already declares its own `render` as `ReactElement | null`, so the gap is
161
+ * `useFrontendTool`'s.)
162
+ *
163
+ * OPT-IN, and only that. It changes no hook signature: a renderer written
164
+ * inline in a `useFrontendTool` call is still checked against core's
165
+ * `ReactNode`-returning contract, and a bare string still compiles there. This
166
+ * type gives the narrowing back on renderers you annotate; it does not make the
167
+ * package safe.
168
+ *
169
+ * DERIVED from core's canonical `ReactToolCallRenderer` contract rather than
170
+ * declared separately: the props come from it unchanged through
171
+ * `React.ComponentProps`, and only the return type is React Native's. That is
172
+ * deliberate — the last time this package declared its own render-prop shape it
173
+ * drifted from the contract (`{ args: T; status: "executing" | "complete";
174
+ * result?: string }`: no `name`, no `toolCallId`, no in-progress arm, and `args`
175
+ * unconditionally complete). Deriving means a change to the contract changes
176
+ * this type with it, and `check-types` names every renderer that breaks.
177
+ *
178
+ * @typeParam T - The parsed tool arguments; the same `T` as `useFrontendTool`'s.
179
+ *
180
+ * @example
181
+ * ```tsx
182
+ * import { useFrontendTool } from "@copilotkit/react-native/headless";
183
+ * import type { FrontendToolRenderFunction } from "@copilotkit/react-native/headless";
184
+ * import { Text } from "react-native";
185
+ * import { z } from "zod";
186
+ *
187
+ * const renderWeather: FrontendToolRenderFunction<{ city: string }> = ({
188
+ * args,
189
+ * }) => <Text>{args.city}</Text>;
190
+ *
191
+ * useFrontendTool({
192
+ * name: "showWeather",
193
+ * description: "Show the weather",
194
+ * parameters: z.object({ city: z.string() }),
195
+ * handler: async ({ city }) => city,
196
+ * render: renderWeather,
197
+ * });
198
+ * ```
199
+ */
200
+ export type FrontendToolRenderFunction<
201
+ T extends Record<string, unknown> = Record<string, unknown>,
202
+ > = (
203
+ props: React.ComponentProps<ReactToolCallRenderer<T>["render"]>,
204
+ ) => React.ReactElement | null;
@@ -3,9 +3,8 @@ import { render } from "@testing-library/react";
3
3
  import { describe, it, expect } from "vitest";
4
4
  import { z } from "zod";
5
5
  import type { ToolMessage } from "@ag-ui/client";
6
- import { useRenderTool } from "../useRenderTool";
7
- import type { RenderToolProps } from "../render-tool-types";
8
- import { useComponent, useRenderToolCall } from "../../headless";
6
+ import { useComponent, useRenderTool, useRenderToolCall } from "../../headless";
7
+ import type { RenderToolProps } from "../../headless";
9
8
  import { TestCopilotKit } from "../../__mocks__/test-copilotkit";
10
9
  import { toolMessage } from "../../__mocks__/tool-fixtures";
11
10
 
@@ -15,8 +14,12 @@ import { toolMessage } from "../../__mocks__/tool-fixtures";
15
14
  * CopilotKitCoreReact registry, so they also prove the convergence itself.
16
15
  */
17
16
 
18
- /** Args the probe's tool declares, so its render props are typed rather than `any`. */
19
- type AboutArgs = { dataId: string };
17
+ /**
18
+ * The schema the probe's renderer declares, so its render props are typed rather
19
+ * than `any`. react-core's `RenderToolProps` is generic over the SCHEMA (not
20
+ * over the parsed arguments), so the type is read back off this value.
21
+ */
22
+ const aboutSchema = z.object({ dataId: z.string() });
20
23
 
21
24
  /**
22
25
  * Renders one tool call and reports the props the registered renderer saw.
@@ -31,16 +34,15 @@ type AboutArgs = { dataId: string };
31
34
  function renderCall(
32
35
  args: string | undefined,
33
36
  resultMessage?: ToolMessage,
34
- ): RenderToolProps<AboutArgs> {
37
+ ): RenderToolProps<typeof aboutSchema> {
35
38
  // A mutable box rather than a `let`, so the captured value keeps its declared
36
39
  // type after `render()` instead of being narrowed to the `null` initializer.
37
- const seen: { props?: RenderToolProps<AboutArgs> } = {};
40
+ const seen: { props?: RenderToolProps<typeof aboutSchema> } = {};
38
41
 
39
42
  function Probe() {
40
- useRenderTool<AboutArgs>({
43
+ useRenderTool({
41
44
  name: "showAbout",
42
- description: "Show about",
43
- parameters: z.object({ dataId: z.string() }),
45
+ parameters: aboutSchema,
44
46
  render: (props) => {
45
47
  seen.props = props;
46
48
  return null;
@@ -81,19 +83,19 @@ describe("useRenderToolCall on React Native", () => {
81
83
  // `renderCall` throws if the renderer never ran, so reaching this line is
82
84
  // itself the "it rendered" assertion.
83
85
  const props = renderCall('{"dataId":"zosch"}');
84
- expect(props.args).toEqual({ dataId: "zosch" });
86
+ expect(props.parameters).toEqual({ dataId: "zosch" });
85
87
  });
86
88
 
87
- it("exposes PARTIAL args with status inProgress while arguments are incomplete", () => {
89
+ it("exposes PARTIAL parameters with status inProgress while arguments are incomplete", () => {
88
90
  const props = renderCall('{"dataId":"neues-mus');
89
91
  expect(props.status).toBe("inProgress");
90
- expect(props.args).toEqual({ dataId: "neues-mus" });
92
+ expect(props.parameters).toEqual({ dataId: "neues-mus" });
91
93
  });
92
94
 
93
95
  it("does not throw on a fragment with no complete key yet", () => {
94
96
  const props = renderCall('{"places":[{"title":"Roof');
95
97
  expect(props.status).toBe("inProgress");
96
- expect(props.args).toBeTypeOf("object");
98
+ expect(props.parameters).toBeTypeOf("object");
97
99
  });
98
100
 
99
101
  it("reports complete and passes the result through when a tool message exists", () => {
@@ -113,7 +115,7 @@ describe("useRenderToolCall on React Native", () => {
113
115
 
114
116
  it("treats absent arguments as an empty object, not a crash", () => {
115
117
  const props = renderCall(undefined);
116
- expect(props.args).toEqual({});
118
+ expect(props.parameters).toEqual({});
117
119
  });
118
120
 
119
121
  it("returns null for a tool with no registered renderer", () => {