@copilotkit/shared 1.80.0 → 1.82.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/dist/a2ui-envelope.cjs +154 -0
- package/dist/a2ui-envelope.cjs.map +1 -0
- package/dist/a2ui-envelope.d.cts +101 -0
- package/dist/a2ui-envelope.d.cts.map +1 -0
- package/dist/a2ui-envelope.d.mts +101 -0
- package/dist/a2ui-envelope.d.mts.map +1 -0
- package/dist/a2ui-envelope.mjs +151 -0
- package/dist/a2ui-envelope.mjs.map +1 -0
- package/dist/a2ui-prompts.cjs +139 -0
- package/dist/a2ui-prompts.cjs.map +1 -1
- package/dist/a2ui-prompts.d.cts +60 -1
- package/dist/a2ui-prompts.d.cts.map +1 -1
- package/dist/a2ui-prompts.d.mts +60 -1
- package/dist/a2ui-prompts.d.mts.map +1 -1
- package/dist/a2ui-prompts.mjs +134 -1
- package/dist/a2ui-prompts.mjs.map +1 -1
- package/dist/generative-ui/basic-functions.cjs +177 -0
- package/dist/generative-ui/basic-functions.cjs.map +1 -0
- package/dist/generative-ui/basic-functions.d.cts +108 -0
- package/dist/generative-ui/basic-functions.d.cts.map +1 -0
- package/dist/generative-ui/basic-functions.d.mts +108 -0
- package/dist/generative-ui/basic-functions.d.mts.map +1 -0
- package/dist/generative-ui/basic-functions.mjs +167 -0
- package/dist/generative-ui/basic-functions.mjs.map +1 -0
- package/dist/generative-ui/child-refs.cjs +161 -0
- package/dist/generative-ui/child-refs.cjs.map +1 -0
- package/dist/generative-ui/child-refs.d.cts +68 -0
- package/dist/generative-ui/child-refs.d.cts.map +1 -0
- package/dist/generative-ui/child-refs.d.mts +68 -0
- package/dist/generative-ui/child-refs.d.mts.map +1 -0
- package/dist/generative-ui/child-refs.mjs +152 -0
- package/dist/generative-ui/child-refs.mjs.map +1 -0
- package/dist/generative-ui/is-record.cjs +10 -0
- package/dist/generative-ui/is-record.cjs.map +1 -0
- package/dist/generative-ui/is-record.mjs +9 -0
- package/dist/generative-ui/is-record.mjs.map +1 -0
- package/dist/generative-ui/prompt.cjs +91 -0
- package/dist/generative-ui/prompt.cjs.map +1 -0
- package/dist/generative-ui/prompt.d.cts +13 -0
- package/dist/generative-ui/prompt.d.cts.map +1 -0
- package/dist/generative-ui/prompt.d.mts +13 -0
- package/dist/generative-ui/prompt.d.mts.map +1 -0
- package/dist/generative-ui/prompt.mjs +90 -0
- package/dist/generative-ui/prompt.mjs.map +1 -0
- package/dist/generative-ui/render-ui-args.cjs +160 -0
- package/dist/generative-ui/render-ui-args.cjs.map +1 -0
- package/dist/generative-ui/render-ui-args.d.cts +40 -0
- package/dist/generative-ui/render-ui-args.d.cts.map +1 -0
- package/dist/generative-ui/render-ui-args.d.mts +40 -0
- package/dist/generative-ui/render-ui-args.d.mts.map +1 -0
- package/dist/generative-ui/render-ui-args.mjs +159 -0
- package/dist/generative-ui/render-ui-args.mjs.map +1 -0
- package/dist/generative-ui/types.cjs +101 -0
- package/dist/generative-ui/types.cjs.map +1 -0
- package/dist/generative-ui/types.d.cts +270 -0
- package/dist/generative-ui/types.d.cts.map +1 -0
- package/dist/generative-ui/types.d.mts +270 -0
- package/dist/generative-ui/types.d.mts.map +1 -0
- package/dist/generative-ui/types.mjs +86 -0
- package/dist/generative-ui/types.mjs.map +1 -0
- package/dist/generative-ui/validate-operation.cjs +405 -0
- package/dist/generative-ui/validate-operation.cjs.map +1 -0
- package/dist/generative-ui/validate-operation.d.cts +86 -0
- package/dist/generative-ui/validate-operation.d.cts.map +1 -0
- package/dist/generative-ui/validate-operation.d.mts +86 -0
- package/dist/generative-ui/validate-operation.d.mts.map +1 -0
- package/dist/generative-ui/validate-operation.mjs +399 -0
- package/dist/generative-ui/validate-operation.mjs.map +1 -0
- package/dist/index.cjs +63 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +9 -2
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +9 -2
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +9 -2
- package/dist/index.mjs.map +1 -1
- package/dist/index.umd.js +1421 -20
- package/dist/index.umd.js.map +1 -1
- package/dist/package.cjs +1 -1
- package/dist/package.mjs +1 -1
- package/dist/telemetry/telemetry-client.cjs +1 -1
- package/dist/telemetry/telemetry-client.cjs.map +1 -1
- package/dist/telemetry/telemetry-client.d.cts.map +1 -1
- package/dist/telemetry/telemetry-client.d.mts.map +1 -1
- package/dist/telemetry/telemetry-client.mjs +1 -1
- package/dist/telemetry/telemetry-client.mjs.map +1 -1
- package/dist/utils/dashboard-url.cjs +19 -0
- package/dist/utils/dashboard-url.cjs.map +1 -0
- package/dist/utils/dashboard-url.mjs +18 -0
- package/dist/utils/dashboard-url.mjs.map +1 -0
- package/dist/utils/index.cjs +2 -1
- package/dist/utils/index.cjs.map +1 -1
- package/dist/utils/index.d.cts.map +1 -1
- package/dist/utils/index.d.mts.map +1 -1
- package/dist/utils/index.mjs +2 -1
- package/dist/utils/index.mjs.map +1 -1
- package/dist/utils/inspector-learning.cjs +10 -7
- package/dist/utils/inspector-learning.cjs.map +1 -1
- package/dist/utils/inspector-learning.d.cts.map +1 -1
- package/dist/utils/inspector-learning.d.mts.map +1 -1
- package/dist/utils/inspector-learning.mjs +11 -7
- package/dist/utils/inspector-learning.mjs.map +1 -1
- package/dist/utils/inspector-metadata.cjs +2 -3
- package/dist/utils/inspector-metadata.cjs.map +1 -1
- package/dist/utils/inspector-metadata.d.cts.map +1 -1
- package/dist/utils/inspector-metadata.d.mts.map +1 -1
- package/dist/utils/inspector-metadata.mjs +3 -3
- package/dist/utils/inspector-metadata.mjs.map +1 -1
- package/package.json +1 -1
- package/src/__tests__/a2ui-envelope.test.ts +434 -0
- package/src/__tests__/a2ui-prompts.test.ts +362 -0
- package/src/a2ui-envelope.ts +309 -0
- package/src/a2ui-prompts.ts +207 -0
- package/src/generative-ui/__tests__/render-ui-args.test.ts +175 -0
- package/src/generative-ui/__tests__/validate-operation.test.ts +977 -0
- package/src/generative-ui/basic-functions.ts +282 -0
- package/src/generative-ui/child-refs.ts +210 -0
- package/src/generative-ui/index.ts +6 -0
- package/src/generative-ui/is-record.ts +4 -0
- package/src/generative-ui/prompt.ts +174 -0
- package/src/generative-ui/render-ui-args.ts +199 -0
- package/src/generative-ui/types.ts +314 -0
- package/src/generative-ui/validate-operation.ts +723 -0
- package/src/index.ts +15 -0
- package/src/telemetry/telemetry-client.test.ts +18 -0
- package/src/telemetry/telemetry-client.ts +3 -1
- package/src/utils/dashboard-url.ts +17 -0
- package/src/utils/index.ts +7 -1
- package/src/utils/inspector-learning.test.ts +58 -0
- package/src/utils/inspector-learning.ts +26 -5
- package/src/utils/inspector-metadata.test.ts +2 -1
- package/src/utils/inspector-metadata.ts +3 -13
- package/src/utils.test.ts +71 -0
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { isRecord } from "./is-record";
|
|
2
|
+
export interface ExtractedRenderUIArgs {
|
|
3
|
+
target?: string;
|
|
4
|
+
/**
|
|
5
|
+
* Complete elements of the `operations` array, in order. A balanced element
|
|
6
|
+
* that is not a valid JSON object is returned as `null`.
|
|
7
|
+
*/
|
|
8
|
+
operations: Array<Record<string, unknown> | null>;
|
|
9
|
+
/**
|
|
10
|
+
* Set when an `operations[]` element was opened but its closing brace never
|
|
11
|
+
* arrived: the text ends mid-operation (still streaming, or truncated).
|
|
12
|
+
*/
|
|
13
|
+
incompleteOperation?: boolean;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Reads `target` and every complete `operations[]` element from a possibly
|
|
18
|
+
* truncated `render_ui` argument string.
|
|
19
|
+
*/
|
|
20
|
+
export function extractRenderUIArgs(text: string) {
|
|
21
|
+
return new RenderUIArgsScanner().scan(text);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The parser of {@link extractRenderUIArgs}, with its state kept between
|
|
26
|
+
* calls. Each call scans only the text after the text it scanned before, so
|
|
27
|
+
* a streamed argument string is scanned once in total.
|
|
28
|
+
*/
|
|
29
|
+
class RenderUIArgsScanner {
|
|
30
|
+
private readonly result: ExtractedRenderUIArgs = { operations: [] };
|
|
31
|
+
private readonly stack: Array<"{" | "["> = [];
|
|
32
|
+
private inString = false;
|
|
33
|
+
private escaped = false;
|
|
34
|
+
private stringStart = -1;
|
|
35
|
+
private pendingKey: string | null = null;
|
|
36
|
+
private currentKey: string | null = null;
|
|
37
|
+
private expectingValue = false;
|
|
38
|
+
private inOperations = false;
|
|
39
|
+
private elementStart = -1;
|
|
40
|
+
private scanned = 0;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Scans `text` from where the last call stopped.
|
|
44
|
+
*
|
|
45
|
+
* @param text - The whole text so far. It starts with the text of the
|
|
46
|
+
* last call.
|
|
47
|
+
* @returns The result so far. It is the same object on each call.
|
|
48
|
+
*/
|
|
49
|
+
scan(text: string) {
|
|
50
|
+
const { result, stack } = this;
|
|
51
|
+
let {
|
|
52
|
+
inString,
|
|
53
|
+
escaped,
|
|
54
|
+
stringStart,
|
|
55
|
+
pendingKey,
|
|
56
|
+
currentKey,
|
|
57
|
+
expectingValue,
|
|
58
|
+
inOperations,
|
|
59
|
+
elementStart,
|
|
60
|
+
} = this;
|
|
61
|
+
for (let i = this.scanned; i < text.length; i++) {
|
|
62
|
+
const ch = text[i];
|
|
63
|
+
if (inString) {
|
|
64
|
+
if (escaped) {
|
|
65
|
+
escaped = false;
|
|
66
|
+
} else if (ch === "\\") {
|
|
67
|
+
escaped = true;
|
|
68
|
+
} else if (ch === '"') {
|
|
69
|
+
inString = false;
|
|
70
|
+
if (stack.length === 1) {
|
|
71
|
+
const literal = text.slice(stringStart, i + 1);
|
|
72
|
+
if (expectingValue) {
|
|
73
|
+
if (currentKey === "target") {
|
|
74
|
+
try {
|
|
75
|
+
result.target = JSON.parse(literal);
|
|
76
|
+
} catch {
|
|
77
|
+
// Unreachable for a closed literal; keep scanning.
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
expectingValue = false;
|
|
81
|
+
} else {
|
|
82
|
+
pendingKey = literal;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
switch (ch) {
|
|
89
|
+
case '"':
|
|
90
|
+
inString = true;
|
|
91
|
+
stringStart = i;
|
|
92
|
+
break;
|
|
93
|
+
case ":":
|
|
94
|
+
if (stack.length === 1 && pendingKey !== null) {
|
|
95
|
+
try {
|
|
96
|
+
currentKey = JSON.parse(pendingKey);
|
|
97
|
+
} catch {
|
|
98
|
+
currentKey = null;
|
|
99
|
+
}
|
|
100
|
+
pendingKey = null;
|
|
101
|
+
expectingValue = true;
|
|
102
|
+
}
|
|
103
|
+
break;
|
|
104
|
+
case ",":
|
|
105
|
+
if (stack.length === 1) {
|
|
106
|
+
expectingValue = false;
|
|
107
|
+
currentKey = null;
|
|
108
|
+
}
|
|
109
|
+
break;
|
|
110
|
+
case "{":
|
|
111
|
+
if (inOperations && stack.length === 2) elementStart = i;
|
|
112
|
+
stack.push("{");
|
|
113
|
+
break;
|
|
114
|
+
case "[":
|
|
115
|
+
if (
|
|
116
|
+
stack.length === 1 &&
|
|
117
|
+
expectingValue &&
|
|
118
|
+
currentKey === "operations"
|
|
119
|
+
) {
|
|
120
|
+
inOperations = true;
|
|
121
|
+
}
|
|
122
|
+
stack.push("[");
|
|
123
|
+
break;
|
|
124
|
+
case "}":
|
|
125
|
+
case "]":
|
|
126
|
+
stack.pop();
|
|
127
|
+
if (
|
|
128
|
+
ch === "}" &&
|
|
129
|
+
inOperations &&
|
|
130
|
+
stack.length === 2 &&
|
|
131
|
+
elementStart >= 0
|
|
132
|
+
) {
|
|
133
|
+
result.operations.push(
|
|
134
|
+
parseObject(text.slice(elementStart, i + 1)),
|
|
135
|
+
);
|
|
136
|
+
elementStart = -1;
|
|
137
|
+
}
|
|
138
|
+
if (ch === "]" && inOperations && stack.length === 1) {
|
|
139
|
+
inOperations = false;
|
|
140
|
+
expectingValue = false;
|
|
141
|
+
}
|
|
142
|
+
break;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
this.inString = inString;
|
|
146
|
+
this.escaped = escaped;
|
|
147
|
+
this.stringStart = stringStart;
|
|
148
|
+
this.pendingKey = pendingKey;
|
|
149
|
+
this.currentKey = currentKey;
|
|
150
|
+
this.expectingValue = expectingValue;
|
|
151
|
+
this.inOperations = inOperations;
|
|
152
|
+
this.elementStart = elementStart;
|
|
153
|
+
this.scanned = text.length;
|
|
154
|
+
if (elementStart >= 0) result.incompleteOperation = true;
|
|
155
|
+
else delete result.incompleteOperation;
|
|
156
|
+
return result;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function parseObject(raw: string) {
|
|
161
|
+
try {
|
|
162
|
+
const value: unknown = JSON.parse(raw);
|
|
163
|
+
return isRecord(value) ? value : null;
|
|
164
|
+
} catch {
|
|
165
|
+
return null;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** Feeds streamed argument deltas and reports operations not yet seen. */
|
|
170
|
+
export class RenderUIArgsStream {
|
|
171
|
+
private buffer = "";
|
|
172
|
+
private emitted = 0;
|
|
173
|
+
private incomplete = false;
|
|
174
|
+
private readonly scanner = new RenderUIArgsScanner();
|
|
175
|
+
|
|
176
|
+
push(delta: string) {
|
|
177
|
+
this.buffer += delta;
|
|
178
|
+
const { target, operations, incompleteOperation } = this.scanner.scan(
|
|
179
|
+
this.buffer,
|
|
180
|
+
);
|
|
181
|
+
const newOperations = operations.slice(this.emitted);
|
|
182
|
+
this.emitted = operations.length;
|
|
183
|
+
this.incomplete = incompleteOperation === true;
|
|
184
|
+
return { target, newOperations };
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Every argument delta received so far, concatenated. */
|
|
188
|
+
get text() {
|
|
189
|
+
return this.buffer;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* True when the text received so far ends inside an `operations[]` element.
|
|
194
|
+
* Once the tool call has ended, that element was truncated.
|
|
195
|
+
*/
|
|
196
|
+
get hasIncompleteOperation() {
|
|
197
|
+
return this.incomplete;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
/** A2UI protocol version used on the wire. */
|
|
2
|
+
export const A2UI_VERSION = "v1.0";
|
|
3
|
+
/** Activity type of a generated surface message. */
|
|
4
|
+
export const GENERATIVE_UI_ACTIVITY_TYPE = "generative-ui-surface";
|
|
5
|
+
/** Activity type of a function call that the agent asks the client to run. */
|
|
6
|
+
export const GENERATIVE_UI_FUNCTION_CALL_ACTIVITY_TYPE =
|
|
7
|
+
"generative-ui-function-call";
|
|
8
|
+
/** Tool the model calls to render or update surfaces. */
|
|
9
|
+
export const GENERATIVE_UI_RENDER_TOOL = "render_ui";
|
|
10
|
+
/** Target id of the chat transcript. */
|
|
11
|
+
export const GENERATIVE_UI_CHAT_TARGET = "chat";
|
|
12
|
+
/** Component id every surface renders from. */
|
|
13
|
+
export const GENERATIVE_UI_ROOT_ID = "root";
|
|
14
|
+
/**
|
|
15
|
+
* Whether the agent may call renderer functions with `callRendererFunction`.
|
|
16
|
+
* Off for now: the result goes back as a developer message, and not every
|
|
17
|
+
* backend keeps that message where the model reads it in order. While off,
|
|
18
|
+
* the prompts do not mention the operation, the validator rejects it, and
|
|
19
|
+
* the dispatcher refuses the agent, whatever a declaration's
|
|
20
|
+
* `allowedCallers` says. The code and its tests stay for when it is on.
|
|
21
|
+
*/
|
|
22
|
+
export const GENERATIVE_UI_AGENT_FUNCTION_CALLS = false;
|
|
23
|
+
/** The reason an agent function call is rejected while they are off. */
|
|
24
|
+
export const GENERATIVE_UI_AGENT_FUNCTION_CALLS_OFF_REASON =
|
|
25
|
+
"callRendererFunction is not supported in this version: the agent cannot call renderer functions until their results can be sent back to it reliably";
|
|
26
|
+
|
|
27
|
+
/** Activity message id of a surface. One message per surface. */
|
|
28
|
+
export function generativeUISurfaceMessageId(surfaceId: string) {
|
|
29
|
+
return `genui:${surfaceId}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Activity message id of an agent-called function. One message per
|
|
34
|
+
* `functionCallId`.
|
|
35
|
+
*
|
|
36
|
+
* @param functionCallId - The `functionCallId` of the `callRendererFunction` operation.
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* ```ts
|
|
40
|
+
* generativeUIFunctionCallMessageId("f1"); // "genui-fn:f1"
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export function generativeUIFunctionCallMessageId(functionCallId: string) {
|
|
44
|
+
return `genui-fn:${functionCallId}`;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
import type {
|
|
48
|
+
A2UIFunctionPermissions,
|
|
49
|
+
A2UIFunctionReturnType,
|
|
50
|
+
} from "./basic-functions";
|
|
51
|
+
|
|
52
|
+
// Named `GenerativeUIJSONSchema` because the package root already exports a
|
|
53
|
+
// `JSONSchema` (utils/json-schema.ts); the bare name would collide.
|
|
54
|
+
export type GenerativeUIJSONSchema = Record<string, unknown>;
|
|
55
|
+
|
|
56
|
+
export type A2UIComponentNode = {
|
|
57
|
+
id: string;
|
|
58
|
+
component: string;
|
|
59
|
+
[prop: string]: unknown;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The keys of the A2UI 1.0 component envelope next to `id` and
|
|
64
|
+
* `component`: `catalogId`, `accessibility` and `metadata`. They are not
|
|
65
|
+
* props of the component. The renderer reads `accessibility` and ignores
|
|
66
|
+
* the other two.
|
|
67
|
+
*/
|
|
68
|
+
export const A2UI_COMPONENT_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
|
|
69
|
+
"catalogId",
|
|
70
|
+
"accessibility",
|
|
71
|
+
"metadata",
|
|
72
|
+
]);
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* A call of a named function: `{ "@call": "addToCart", "args": { ... } }`.
|
|
76
|
+
* Without `catalogId`, the function comes from the catalog of the run.
|
|
77
|
+
*/
|
|
78
|
+
export type A2UIFunctionCall = {
|
|
79
|
+
"@call": string;
|
|
80
|
+
args?: Record<string, unknown>;
|
|
81
|
+
catalogId?: string;
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
export type A2UIOperation =
|
|
85
|
+
| {
|
|
86
|
+
version: "v1.0";
|
|
87
|
+
createSurface: {
|
|
88
|
+
surfaceId: string;
|
|
89
|
+
/** Left out by the model. The run's catalog id is filled in. */
|
|
90
|
+
catalogId?: string;
|
|
91
|
+
/** Components to add at once, checked like `updateComponents`. */
|
|
92
|
+
components?: A2UIComponentNode[];
|
|
93
|
+
/** The initial root data model. */
|
|
94
|
+
dataModel?: Record<string, unknown>;
|
|
95
|
+
sendDataModel?: boolean;
|
|
96
|
+
metadata?: { extensions?: Record<string, unknown> };
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
| {
|
|
100
|
+
version: "v1.0";
|
|
101
|
+
updateComponents: { surfaceId: string; components: A2UIComponentNode[] };
|
|
102
|
+
}
|
|
103
|
+
| {
|
|
104
|
+
version: "v1.0";
|
|
105
|
+
/**
|
|
106
|
+
* Sets `value` at `path`. A `null` value deletes the key at `path`.
|
|
107
|
+
* With no `path`, or `"/"`, it sets the whole data model.
|
|
108
|
+
*/
|
|
109
|
+
updateDataModel: { surfaceId: string; path?: string; value: unknown };
|
|
110
|
+
}
|
|
111
|
+
| { version: "v1.0"; deleteSurface: { surfaceId: string } }
|
|
112
|
+
| {
|
|
113
|
+
version: "v1.0";
|
|
114
|
+
/** Runs an app function in the browser, with no user interaction. */
|
|
115
|
+
callRendererFunction: {
|
|
116
|
+
functionCallId: string;
|
|
117
|
+
callFunction: A2UIFunctionCall;
|
|
118
|
+
};
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
/** Value of an event prop: run a host function, or report the event to the agent. */
|
|
122
|
+
export type GenerativeUIActionBinding =
|
|
123
|
+
| {
|
|
124
|
+
event: {
|
|
125
|
+
name: string;
|
|
126
|
+
/**
|
|
127
|
+
* First line of the user message that the event becomes: text, a
|
|
128
|
+
* data binding, or a function value such as formatString.
|
|
129
|
+
*/
|
|
130
|
+
userMessage?: string | { "@path": string } | A2UIFunctionCall;
|
|
131
|
+
context?: Record<string, unknown>;
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
| { functionCall: A2UIFunctionCall };
|
|
135
|
+
|
|
136
|
+
export type GenerativeUISurfaceStatus = "streaming" | "ready" | "error";
|
|
137
|
+
|
|
138
|
+
export interface GenerativeUIRejectedOperation {
|
|
139
|
+
/** Position of the operation in the render_ui call, or in the content list. */
|
|
140
|
+
index: number;
|
|
141
|
+
reason: string;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Content of a `generative-ui-surface` activity message. */
|
|
145
|
+
export interface GenerativeUISurfaceContent {
|
|
146
|
+
surfaceId: string;
|
|
147
|
+
target: string;
|
|
148
|
+
catalogId: string;
|
|
149
|
+
/** Committed (validated) operations, cumulative. */
|
|
150
|
+
operations: A2UIOperation[];
|
|
151
|
+
status: GenerativeUISurfaceStatus;
|
|
152
|
+
rejected: GenerativeUIRejectedOperation[];
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Content of a `generative-ui-function-call` activity message. */
|
|
156
|
+
export interface GenerativeUIFunctionCallContent {
|
|
157
|
+
functionCallId: string;
|
|
158
|
+
callFunction: A2UIFunctionCall;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Value of a "multiple" slot that repeats one component for each item of the
|
|
163
|
+
* list at `path`. Paths inside the repeated component are relative to the item.
|
|
164
|
+
*/
|
|
165
|
+
export type GenerativeUITemplateChildren = {
|
|
166
|
+
componentId: string;
|
|
167
|
+
path: string;
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
export interface GenerativeUIComponentManifest {
|
|
171
|
+
/** CopilotKit positional order across model-visible props, slots and events.
|
|
172
|
+
* Exporters encode this as JSON Schema property order; it is not an A2UI keyword. */
|
|
173
|
+
parameterOrder?: readonly string[];
|
|
174
|
+
description?: string;
|
|
175
|
+
props: GenerativeUIJSONSchema;
|
|
176
|
+
events?: Record<
|
|
177
|
+
string,
|
|
178
|
+
{ description?: string; parameters: GenerativeUIJSONSchema }
|
|
179
|
+
>;
|
|
180
|
+
/**
|
|
181
|
+
* Props that hold child components. A "single" slot takes one component id.
|
|
182
|
+
* A "multiple" slot takes a `string[]` of component ids, or a
|
|
183
|
+
* {@link GenerativeUITemplateChildren} template.
|
|
184
|
+
*/
|
|
185
|
+
slots?: Record<string, "single" | "multiple">;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export interface GenerativeUIFunctionManifest extends A2UIFunctionPermissions {
|
|
189
|
+
description?: string;
|
|
190
|
+
parameters: GenerativeUIJSONSchema;
|
|
191
|
+
/** What the function gives back, as A2UI 1.0 names it. */
|
|
192
|
+
returnType?: A2UIFunctionReturnType;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** Serializable description of what the browser can render and call. */
|
|
196
|
+
export interface GenerativeUIManifest {
|
|
197
|
+
/** The catalog of the run. A surface with no `catalogId` gets this one. */
|
|
198
|
+
catalogId: string;
|
|
199
|
+
/**
|
|
200
|
+
* Every catalog that a `catalogId` can name: `catalogId` first, then the
|
|
201
|
+
* catalogs of `extends`. Left out, only `catalogId`.
|
|
202
|
+
*/
|
|
203
|
+
catalogIds?: string[];
|
|
204
|
+
components: Record<string, GenerativeUIComponentManifest>;
|
|
205
|
+
functions: Record<string, GenerativeUIFunctionManifest>;
|
|
206
|
+
/**
|
|
207
|
+
* Places where the model can render surfaces. Only mounted targets are
|
|
208
|
+
* listed. `description` tells the model where the target is on the page
|
|
209
|
+
* and what to put in it.
|
|
210
|
+
*/
|
|
211
|
+
targets: GenerativeUITarget[];
|
|
212
|
+
/** Surfaces the client already holds for the current thread. */
|
|
213
|
+
surfaces: Record<string, GenerativeUISurfaceSummary>;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** A place where the model can render surfaces. */
|
|
217
|
+
export interface GenerativeUITarget {
|
|
218
|
+
id: string;
|
|
219
|
+
kind: "chat" | "inline";
|
|
220
|
+
description?: string;
|
|
221
|
+
/**
|
|
222
|
+
* The only components that the surfaces of this target can use, at most
|
|
223
|
+
* {@link GENERATIVE_UI_MAX_TARGET_COMPONENTS} names. Left out, the target
|
|
224
|
+
* takes every component of the catalog.
|
|
225
|
+
*/
|
|
226
|
+
components?: string[];
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** Most component names that one target can list. */
|
|
230
|
+
export const GENERATIVE_UI_MAX_TARGET_COMPONENTS = 100;
|
|
231
|
+
|
|
232
|
+
/** Most rejections that a surface summary lists. */
|
|
233
|
+
export const GENERATIVE_UI_MAX_SUMMARY_REJECTIONS = 20;
|
|
234
|
+
/** Most characters of one rejection in a surface summary. */
|
|
235
|
+
export const GENERATIVE_UI_MAX_REJECTION_LENGTH = 500;
|
|
236
|
+
|
|
237
|
+
/** One surface that the client holds, as the model sees it. */
|
|
238
|
+
export interface GenerativeUISurfaceSummary {
|
|
239
|
+
target: string;
|
|
240
|
+
/** The values that the user set, by path. Left out when there are none. */
|
|
241
|
+
dataModel?: Record<string, unknown>;
|
|
242
|
+
/**
|
|
243
|
+
* Operations that the client dropped, as `"operation <index>: <reason>"`.
|
|
244
|
+
* At most {@link GENERATIVE_UI_MAX_SUMMARY_REJECTIONS} entries of at most
|
|
245
|
+
* {@link GENERATIVE_UI_MAX_REJECTION_LENGTH} characters. Left out when
|
|
246
|
+
* there are none.
|
|
247
|
+
*/
|
|
248
|
+
rejected?: string[];
|
|
249
|
+
/**
|
|
250
|
+
* Left out while the surface exists. `"deleted"`: a deleteSurface removed
|
|
251
|
+
* it, and its id cannot be used again. `"failed"`: its createSurface was
|
|
252
|
+
* rejected, so it does not exist; a corrected createSurface can use the id.
|
|
253
|
+
*/
|
|
254
|
+
status?: "deleted" | "failed";
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/** A user interaction bound to `{ event }`, sent to the agent. */
|
|
258
|
+
export interface GenerativeUIUserEvent {
|
|
259
|
+
name: string;
|
|
260
|
+
surfaceId: string;
|
|
261
|
+
componentId: string;
|
|
262
|
+
context: Record<string, unknown>;
|
|
263
|
+
/** The resolved `event.userMessage`: the first line of the user message. */
|
|
264
|
+
userMessage?: string;
|
|
265
|
+
/** When the user acted, as an ISO 8601 string. Filled in when left out. */
|
|
266
|
+
timestamp?: string;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* The A2UI 1.0 action message of a user event: what a renderer sends to the
|
|
271
|
+
* agent when the user triggers an `{ event }` action. The run that the
|
|
272
|
+
* event starts carries it in the envelope (`copilotkit_action`), next to
|
|
273
|
+
* the visible user message.
|
|
274
|
+
*/
|
|
275
|
+
export interface A2UIActionMessage {
|
|
276
|
+
version: typeof A2UI_VERSION;
|
|
277
|
+
action: {
|
|
278
|
+
name: string;
|
|
279
|
+
surfaceId: string;
|
|
280
|
+
sourceComponentId: string;
|
|
281
|
+
/** ISO 8601. */
|
|
282
|
+
timestamp: string;
|
|
283
|
+
userMessage?: string;
|
|
284
|
+
context: Record<string, unknown>;
|
|
285
|
+
};
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/**
|
|
289
|
+
* The action message of a user event, with the A2UI field names. Takes the
|
|
290
|
+
* time of the call when the event has no timestamp.
|
|
291
|
+
*
|
|
292
|
+
* @example
|
|
293
|
+
* ```ts
|
|
294
|
+
* toA2UIActionMessage({ name: "buy", surfaceId: "s1", componentId: "b", context: { sku: "a" } });
|
|
295
|
+
* // { version: "v1.0", action: { name: "buy", surfaceId: "s1", sourceComponentId: "b", timestamp: "2026-…", context: { sku: "a" } } }
|
|
296
|
+
* ```
|
|
297
|
+
*/
|
|
298
|
+
export function toA2UIActionMessage(
|
|
299
|
+
event: GenerativeUIUserEvent,
|
|
300
|
+
): A2UIActionMessage {
|
|
301
|
+
return {
|
|
302
|
+
version: A2UI_VERSION,
|
|
303
|
+
action: {
|
|
304
|
+
name: event.name,
|
|
305
|
+
surfaceId: event.surfaceId,
|
|
306
|
+
sourceComponentId: event.componentId,
|
|
307
|
+
timestamp: event.timestamp ?? new Date().toISOString(),
|
|
308
|
+
...(event.userMessage === undefined
|
|
309
|
+
? {}
|
|
310
|
+
: { userMessage: event.userMessage }),
|
|
311
|
+
context: event.context,
|
|
312
|
+
},
|
|
313
|
+
};
|
|
314
|
+
}
|