@copilotkit/react-native 1.70.2 → 1.71.0
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.
- package/USAGE.md +76 -5
- package/dist/headless.cjs +1 -1
- package/dist/headless.d.cts +59 -3
- package/dist/headless.d.mts +59 -3
- package/dist/headless.mjs +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.mts +3 -3
- package/dist/index.mjs +1 -1
- package/dist/useRenderTool-DFz206nL.d.cts +149 -0
- package/dist/useRenderTool-DsCxzyAP.d.mts +149 -0
- package/dist/useRenderTool-L3Rw6SYD.cjs +298 -0
- package/dist/useRenderTool-L3Rw6SYD.cjs.map +1 -0
- package/dist/useRenderTool-pLM3upcs.mjs +285 -0
- package/dist/useRenderTool-pLM3upcs.mjs.map +1 -0
- package/package.json +4 -4
- package/src/__mocks__/test-copilotkit.tsx +14 -2
- package/src/__tests__/frontend-tool-render.test-d.tsx +148 -0
- package/src/__tests__/headless-entry-surface.test.ts +232 -2
- package/src/__tests__/headless-value-exports.test.ts +16 -5
- package/src/components/__tests__/CopilotChatToolCalls.test.tsx +26 -22
- package/src/headless.ts +79 -7
- package/src/hooks/__tests__/render-tool-call.integration.test.tsx +17 -15
- package/src/hooks/__tests__/useRenderTool.test.tsx +733 -202
- package/src/hooks/useRenderTool.ts +482 -49
- package/dist/useRenderTool-BBxnOOeJ.d.mts +0 -161
- package/dist/useRenderTool-BWo11PCL.d.cts +0 -161
- package/dist/useRenderTool-CKEPq7MQ.cjs +0 -162
- package/dist/useRenderTool-CKEPq7MQ.cjs.map +0 -1
- package/dist/useRenderTool-l7M-I8rT.mjs +0 -149
- package/dist/useRenderTool-l7M-I8rT.mjs.map +0 -1
- package/src/hooks/index.ts +0 -3
- 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 "../../
|
|
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
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
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
|
|
51
|
-
render: ({
|
|
52
|
-
<div data-testid="places">{`${status}:${
|
|
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,
|
|
59
|
-
// output of the `toolCallId -> ToolMessage` correlation: the status it
|
|
60
|
-
// the
|
|
61
|
-
// `undefined` is spelled out rather than stringified, so an absent
|
|
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: ({
|
|
72
|
+
render: ({ parameters, status, result }) => (
|
|
69
73
|
<div data-testid="report">
|
|
70
|
-
{`${status}:${
|
|
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
|
|
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: ({
|
|
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
|
|
119
|
-
//
|
|
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 {
|
|
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 "
|
|
7
|
-
import type { RenderToolProps } from "
|
|
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
|
-
/**
|
|
19
|
-
|
|
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<
|
|
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<
|
|
40
|
+
const seen: { props?: RenderToolProps<typeof aboutSchema> } = {};
|
|
38
41
|
|
|
39
42
|
function Probe() {
|
|
40
|
-
useRenderTool
|
|
43
|
+
useRenderTool({
|
|
41
44
|
name: "showAbout",
|
|
42
|
-
|
|
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.
|
|
86
|
+
expect(props.parameters).toEqual({ dataId: "zosch" });
|
|
85
87
|
});
|
|
86
88
|
|
|
87
|
-
it("exposes PARTIAL
|
|
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.
|
|
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.
|
|
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.
|
|
118
|
+
expect(props.parameters).toEqual({});
|
|
117
119
|
});
|
|
118
120
|
|
|
119
121
|
it("returns null for a tool with no registered renderer", () => {
|