@copilotkit/shared 1.79.2-canary.1792172552 → 1.81.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.
Files changed (156) hide show
  1. package/dist/a2ui-envelope.cjs +154 -0
  2. package/dist/a2ui-envelope.cjs.map +1 -0
  3. package/dist/a2ui-envelope.d.cts +101 -0
  4. package/dist/a2ui-envelope.d.cts.map +1 -0
  5. package/dist/a2ui-envelope.d.mts +101 -0
  6. package/dist/a2ui-envelope.d.mts.map +1 -0
  7. package/dist/a2ui-envelope.mjs +151 -0
  8. package/dist/a2ui-envelope.mjs.map +1 -0
  9. package/dist/a2ui-prompts.cjs +139 -0
  10. package/dist/a2ui-prompts.cjs.map +1 -1
  11. package/dist/a2ui-prompts.d.cts +60 -1
  12. package/dist/a2ui-prompts.d.cts.map +1 -1
  13. package/dist/a2ui-prompts.d.mts +60 -1
  14. package/dist/a2ui-prompts.d.mts.map +1 -1
  15. package/dist/a2ui-prompts.mjs +134 -1
  16. package/dist/a2ui-prompts.mjs.map +1 -1
  17. package/dist/constants/index.cjs +7 -0
  18. package/dist/constants/index.cjs.map +1 -1
  19. package/dist/constants/index.d.cts +7 -1
  20. package/dist/constants/index.d.cts.map +1 -1
  21. package/dist/constants/index.d.mts +7 -1
  22. package/dist/constants/index.d.mts.map +1 -1
  23. package/dist/constants/index.mjs +7 -1
  24. package/dist/constants/index.mjs.map +1 -1
  25. package/dist/event-transforms/open-generative-ui-middleware.cjs +7 -6
  26. package/dist/event-transforms/open-generative-ui-middleware.cjs.map +1 -1
  27. package/dist/event-transforms/open-generative-ui-middleware.d.cts.map +1 -1
  28. package/dist/event-transforms/open-generative-ui-middleware.d.mts.map +1 -1
  29. package/dist/event-transforms/open-generative-ui-middleware.mjs +7 -6
  30. package/dist/event-transforms/open-generative-ui-middleware.mjs.map +1 -1
  31. package/dist/generative-ui/basic-functions.cjs +177 -0
  32. package/dist/generative-ui/basic-functions.cjs.map +1 -0
  33. package/dist/generative-ui/basic-functions.d.cts +108 -0
  34. package/dist/generative-ui/basic-functions.d.cts.map +1 -0
  35. package/dist/generative-ui/basic-functions.d.mts +108 -0
  36. package/dist/generative-ui/basic-functions.d.mts.map +1 -0
  37. package/dist/generative-ui/basic-functions.mjs +167 -0
  38. package/dist/generative-ui/basic-functions.mjs.map +1 -0
  39. package/dist/generative-ui/child-refs.cjs +161 -0
  40. package/dist/generative-ui/child-refs.cjs.map +1 -0
  41. package/dist/generative-ui/child-refs.d.cts +68 -0
  42. package/dist/generative-ui/child-refs.d.cts.map +1 -0
  43. package/dist/generative-ui/child-refs.d.mts +68 -0
  44. package/dist/generative-ui/child-refs.d.mts.map +1 -0
  45. package/dist/generative-ui/child-refs.mjs +152 -0
  46. package/dist/generative-ui/child-refs.mjs.map +1 -0
  47. package/dist/generative-ui/is-record.cjs +10 -0
  48. package/dist/generative-ui/is-record.cjs.map +1 -0
  49. package/dist/generative-ui/is-record.mjs +9 -0
  50. package/dist/generative-ui/is-record.mjs.map +1 -0
  51. package/dist/generative-ui/prompt.cjs +91 -0
  52. package/dist/generative-ui/prompt.cjs.map +1 -0
  53. package/dist/generative-ui/prompt.d.cts +13 -0
  54. package/dist/generative-ui/prompt.d.cts.map +1 -0
  55. package/dist/generative-ui/prompt.d.mts +13 -0
  56. package/dist/generative-ui/prompt.d.mts.map +1 -0
  57. package/dist/generative-ui/prompt.mjs +90 -0
  58. package/dist/generative-ui/prompt.mjs.map +1 -0
  59. package/dist/generative-ui/render-ui-args.cjs +160 -0
  60. package/dist/generative-ui/render-ui-args.cjs.map +1 -0
  61. package/dist/generative-ui/render-ui-args.d.cts +40 -0
  62. package/dist/generative-ui/render-ui-args.d.cts.map +1 -0
  63. package/dist/generative-ui/render-ui-args.d.mts +40 -0
  64. package/dist/generative-ui/render-ui-args.d.mts.map +1 -0
  65. package/dist/generative-ui/render-ui-args.mjs +159 -0
  66. package/dist/generative-ui/render-ui-args.mjs.map +1 -0
  67. package/dist/generative-ui/types.cjs +101 -0
  68. package/dist/generative-ui/types.cjs.map +1 -0
  69. package/dist/generative-ui/types.d.cts +270 -0
  70. package/dist/generative-ui/types.d.cts.map +1 -0
  71. package/dist/generative-ui/types.d.mts +270 -0
  72. package/dist/generative-ui/types.d.mts.map +1 -0
  73. package/dist/generative-ui/types.mjs +86 -0
  74. package/dist/generative-ui/types.mjs.map +1 -0
  75. package/dist/generative-ui/validate-operation.cjs +405 -0
  76. package/dist/generative-ui/validate-operation.cjs.map +1 -0
  77. package/dist/generative-ui/validate-operation.d.cts +86 -0
  78. package/dist/generative-ui/validate-operation.d.cts.map +1 -0
  79. package/dist/generative-ui/validate-operation.d.mts +86 -0
  80. package/dist/generative-ui/validate-operation.d.mts.map +1 -0
  81. package/dist/generative-ui/validate-operation.mjs +399 -0
  82. package/dist/generative-ui/validate-operation.mjs.map +1 -0
  83. package/dist/index.cjs +64 -0
  84. package/dist/index.cjs.map +1 -1
  85. package/dist/index.d.cts +11 -4
  86. package/dist/index.d.cts.map +1 -1
  87. package/dist/index.d.mts +11 -4
  88. package/dist/index.d.mts.map +1 -1
  89. package/dist/index.mjs +10 -3
  90. package/dist/index.mjs.map +1 -1
  91. package/dist/index.umd.js +1466 -29
  92. package/dist/index.umd.js.map +1 -1
  93. package/dist/package.cjs +1 -1
  94. package/dist/package.mjs +1 -1
  95. package/dist/telemetry/lambda-client.cjs.map +1 -1
  96. package/dist/telemetry/lambda-client.mjs.map +1 -1
  97. package/dist/telemetry/utils.cjs +0 -2
  98. package/dist/telemetry/utils.cjs.map +1 -1
  99. package/dist/telemetry/utils.mjs +0 -2
  100. package/dist/telemetry/utils.mjs.map +1 -1
  101. package/dist/utils/dashboard-url.cjs +19 -0
  102. package/dist/utils/dashboard-url.cjs.map +1 -0
  103. package/dist/utils/dashboard-url.mjs +18 -0
  104. package/dist/utils/dashboard-url.mjs.map +1 -0
  105. package/dist/utils/index.cjs +2 -1
  106. package/dist/utils/index.cjs.map +1 -1
  107. package/dist/utils/index.d.cts +1 -1
  108. package/dist/utils/index.d.cts.map +1 -1
  109. package/dist/utils/index.d.mts +1 -1
  110. package/dist/utils/index.d.mts.map +1 -1
  111. package/dist/utils/index.mjs +2 -1
  112. package/dist/utils/index.mjs.map +1 -1
  113. package/dist/utils/inspector-learning.cjs +48 -16
  114. package/dist/utils/inspector-learning.cjs.map +1 -1
  115. package/dist/utils/inspector-learning.d.cts +14 -1
  116. package/dist/utils/inspector-learning.d.cts.map +1 -1
  117. package/dist/utils/inspector-learning.d.mts +14 -1
  118. package/dist/utils/inspector-learning.d.mts.map +1 -1
  119. package/dist/utils/inspector-learning.mjs +49 -16
  120. package/dist/utils/inspector-learning.mjs.map +1 -1
  121. package/dist/utils/inspector-metadata.cjs +2 -3
  122. package/dist/utils/inspector-metadata.cjs.map +1 -1
  123. package/dist/utils/inspector-metadata.d.cts.map +1 -1
  124. package/dist/utils/inspector-metadata.d.mts.map +1 -1
  125. package/dist/utils/inspector-metadata.mjs +3 -3
  126. package/dist/utils/inspector-metadata.mjs.map +1 -1
  127. package/package.json +3 -4
  128. package/src/__tests__/a2ui-envelope.test.ts +434 -0
  129. package/src/__tests__/a2ui-prompts.test.ts +362 -0
  130. package/src/a2ui-envelope.ts +309 -0
  131. package/src/a2ui-prompts.ts +207 -0
  132. package/src/constants/index.ts +7 -0
  133. package/src/event-transforms/open-generative-ui-middleware.ts +19 -10
  134. package/src/generative-ui/__tests__/render-ui-args.test.ts +175 -0
  135. package/src/generative-ui/__tests__/validate-operation.test.ts +977 -0
  136. package/src/generative-ui/basic-functions.ts +282 -0
  137. package/src/generative-ui/child-refs.ts +210 -0
  138. package/src/generative-ui/index.ts +6 -0
  139. package/src/generative-ui/is-record.ts +4 -0
  140. package/src/generative-ui/prompt.ts +174 -0
  141. package/src/generative-ui/render-ui-args.ts +199 -0
  142. package/src/generative-ui/types.ts +314 -0
  143. package/src/generative-ui/validate-operation.ts +723 -0
  144. package/src/index.ts +15 -0
  145. package/src/telemetry/lambda-client.ts +3 -3
  146. package/src/telemetry/utils.ts +0 -28
  147. package/src/utils/dashboard-url.ts +17 -0
  148. package/src/utils/index.ts +7 -1
  149. package/src/utils/inspector-learning.test.ts +210 -0
  150. package/src/utils/inspector-learning.ts +117 -17
  151. package/src/utils/inspector-metadata.test.ts +2 -1
  152. package/src/utils/inspector-metadata.ts +3 -13
  153. package/src/utils.test.ts +71 -0
  154. package/tsdown.config.ts +0 -1
  155. package/src/telemetry/scarf-client.ts +0 -39
  156. package/src/telemetry/security-check.ts +0 -0
@@ -0,0 +1,177 @@
1
+
2
+ //#region src/generative-ui/basic-functions.ts
3
+ /**
4
+ * The callers of an app function that names none: the renderer only, as
5
+ * in A2UI 1.0. The agent calls a function with `callRendererFunction` only
6
+ * when its declaration allows it (`"rendererOrAgent"` or `"agentOnly"`).
7
+ * The manifests and the exported catalog write the value out.
8
+ */
9
+ const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS = "rendererOnly";
10
+ /**
11
+ * Who may call a function, from its permissions. A function that needs a
12
+ * user gesture is for the renderer only, whatever `allowedCallers` says.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * functionCallers({}); // { renderer: true, agent: true }
17
+ * functionCallers({ allowedCallers: "rendererOnly" }); // { renderer: true, agent: false }
18
+ * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }
19
+ * ```
20
+ */
21
+ function functionCallers(fn) {
22
+ if (fn.requiresUserActivation) return {
23
+ renderer: true,
24
+ agent: false
25
+ };
26
+ const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;
27
+ return {
28
+ renderer: callers !== "agentOnly",
29
+ agent: callers !== "rendererOnly"
30
+ };
31
+ }
32
+ /** Marks a table of built-in functions as callable by the renderer only. */
33
+ function rendererOnly(functions) {
34
+ return Object.fromEntries(Object.entries(functions).map(([name, info]) => [name, {
35
+ ...info,
36
+ allowedCallers: "rendererOnly"
37
+ }]));
38
+ }
39
+ /**
40
+ * The basic functions by name. A `{"@call"}` in a prop, in an event
41
+ * binding, or in a `callRendererFunction` may name any of them without a
42
+ * declaration in `createGenerativeUI({ functions })`.
43
+ */
44
+ const A2UI_BASIC_FUNCTIONS = rendererOnly({
45
+ required: {
46
+ description: "Valid when the value is not empty",
47
+ parameters: "{ value: unknown }",
48
+ returnType: "validationResult"
49
+ },
50
+ regex: {
51
+ description: "Valid when the value matches the pattern",
52
+ parameters: "{ value: string; pattern: string }",
53
+ returnType: "validationResult"
54
+ },
55
+ length: {
56
+ description: "Valid when the length of the value is within min and max",
57
+ parameters: "{ value: string; min?: number; max?: number }",
58
+ returnType: "validationResult"
59
+ },
60
+ numeric: {
61
+ description: "Valid when the value is a number within min and max",
62
+ parameters: "{ value: number; min?: number; max?: number }",
63
+ returnType: "validationResult"
64
+ },
65
+ email: {
66
+ description: "Valid when the value is an email address",
67
+ parameters: "{ value: string }",
68
+ returnType: "validationResult"
69
+ },
70
+ formatString: {
71
+ description: "Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\${ is a literal",
72
+ parameters: "{ value: string }",
73
+ returnType: "string"
74
+ },
75
+ formatNumber: {
76
+ description: "The number in the locale of the user",
77
+ parameters: "{ value: number; decimals?: number; grouping?: boolean }",
78
+ returnType: "string"
79
+ },
80
+ formatCurrency: {
81
+ description: "The amount as money, with an ISO 4217 currency code",
82
+ parameters: "{ value: number; currency: string; decimals?: number; grouping?: boolean }",
83
+ returnType: "string"
84
+ },
85
+ formatDate: {
86
+ description: "A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"",
87
+ parameters: "{ value: string | number; format: string }",
88
+ returnType: "string"
89
+ },
90
+ pluralize: {
91
+ description: "The string of the plural category of the value",
92
+ parameters: "{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }",
93
+ returnType: "string"
94
+ },
95
+ openUrl: {
96
+ description: "Opens an http(s) URL in a new tab. Only from an event",
97
+ parameters: "{ url: string }",
98
+ returnType: "void",
99
+ requiresUserActivation: true
100
+ },
101
+ and: {
102
+ description: "True when every value is true",
103
+ parameters: "{ values: boolean[] }",
104
+ returnType: "boolean"
105
+ },
106
+ or: {
107
+ description: "True when any value is true",
108
+ parameters: "{ values: boolean[] }",
109
+ returnType: "boolean"
110
+ },
111
+ not: {
112
+ description: "The negated value",
113
+ parameters: "{ value: boolean }",
114
+ returnType: "boolean"
115
+ }
116
+ });
117
+ /**
118
+ * The value functions that CopilotKit adds to the basic catalog, because
119
+ * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named
120
+ * args, and `series` builds a computed list. A catalog may declare its own
121
+ * functions in A2UI, so these are regular catalog functions to the model;
122
+ * a renderer without them rejects the call instead of misrendering.
123
+ */
124
+ const COPILOTKIT_FUNCTIONS = rendererOnly({
125
+ calc: {
126
+ description: "The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name",
127
+ parameters: "{ expression: string; [name: string]: number | string | boolean }",
128
+ returnType: "any",
129
+ extension: true
130
+ },
131
+ series: {
132
+ description: "A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.",
133
+ parameters: "{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }",
134
+ returnType: "array",
135
+ extension: true
136
+ }
137
+ });
138
+ /** Every function a `{"@call"}` may name without a declaration: basic and CopilotKit. */
139
+ const GENERATIVE_UI_FUNCTIONS = {
140
+ ...A2UI_BASIC_FUNCTIONS,
141
+ ...COPILOTKIT_FUNCTIONS
142
+ };
143
+ /** The name of the system function that gives the index of a template item. */
144
+ const A2UI_INDEX_FUNCTION = "@index";
145
+ /** True for a built-in function name: basic, CopilotKit, or `@index`. */
146
+ function isA2UIBasicFunction(name) {
147
+ return name === A2UI_INDEX_FUNCTION || Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name);
148
+ }
149
+ /**
150
+ * True for a built-in function that a prop or a check may call: every one
151
+ * except the functions that need a user gesture.
152
+ */
153
+ function isA2UIValueFunction(name) {
154
+ if (name === A2UI_INDEX_FUNCTION) return true;
155
+ const info = Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name) ? GENERATIVE_UI_FUNCTIONS[name] : void 0;
156
+ return info !== void 0 && !info.requiresUserActivation;
157
+ }
158
+ /** `{ "@call": "<name>", "args"?: {...} }`: a function call value. */
159
+ function isCallBinding(value) {
160
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value["@call"] === "string";
161
+ }
162
+ function isValidationResult(value) {
163
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.valid === "boolean";
164
+ }
165
+
166
+ //#endregion
167
+ exports.A2UI_BASIC_FUNCTIONS = A2UI_BASIC_FUNCTIONS;
168
+ exports.A2UI_INDEX_FUNCTION = A2UI_INDEX_FUNCTION;
169
+ exports.COPILOTKIT_FUNCTIONS = COPILOTKIT_FUNCTIONS;
170
+ exports.GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS = GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;
171
+ exports.GENERATIVE_UI_FUNCTIONS = GENERATIVE_UI_FUNCTIONS;
172
+ exports.functionCallers = functionCallers;
173
+ exports.isA2UIBasicFunction = isA2UIBasicFunction;
174
+ exports.isA2UIValueFunction = isA2UIValueFunction;
175
+ exports.isCallBinding = isCallBinding;
176
+ exports.isValidationResult = isValidationResult;
177
+ //# sourceMappingURL=basic-functions.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"basic-functions.cjs","names":[],"sources":["../../src/generative-ui/basic-functions.ts"],"sourcesContent":["/**\n * The functions of the A2UI 1.0 basic catalog, as the model and the\n * validator see them. The renderer implements them (react-core\n * `generative-ui/functions.ts`); this file holds only what both sides share:\n * the names, the short signatures for the schema the model reads, and who\n * may call each one.\n */\n\n/** What a function gives back, as A2UI 1.0 names it. */\nexport type A2UIFunctionReturnType =\n | \"string\"\n | \"number\"\n | \"boolean\"\n | \"array\"\n | \"object\"\n | \"validationResult\"\n | \"any\"\n | \"void\";\n\n/**\n * Who may call a function. The renderer calls it from an event binding or\n * as a prop value; the agent calls it with `callRendererFunction`.\n */\nexport type A2UIAllowedCallers =\n | \"rendererOnly\"\n | \"agentOnly\"\n | \"rendererOrAgent\";\n\n/**\n * The callers of an app function that names none: the renderer only, as\n * in A2UI 1.0. The agent calls a function with `callRendererFunction` only\n * when its declaration allows it (`\"rendererOrAgent\"` or `\"agentOnly\"`).\n * The manifests and the exported catalog write the value out.\n */\nexport const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS: A2UIAllowedCallers =\n \"rendererOnly\";\n\n/** The A2UI 1.0 interface fields of a function: who calls it, and how. */\nexport interface A2UIFunctionPermissions {\n allowedCallers?: A2UIAllowedCallers;\n /**\n * True for a function that only runs from a user gesture (a click, a key\n * press). It is `rendererOnly`: the agent cannot call it, and a prop\n * cannot be bound to it.\n */\n requiresUserActivation?: boolean;\n}\n\n/**\n * Who may call a function, from its permissions. A function that needs a\n * user gesture is for the renderer only, whatever `allowedCallers` says.\n *\n * @example\n * ```ts\n * functionCallers({}); // { renderer: true, agent: true }\n * functionCallers({ allowedCallers: \"rendererOnly\" }); // { renderer: true, agent: false }\n * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }\n * ```\n */\nexport function functionCallers(fn: A2UIFunctionPermissions) {\n if (fn.requiresUserActivation) return { renderer: true, agent: false };\n const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;\n return {\n renderer: callers !== \"agentOnly\",\n agent: callers !== \"rendererOnly\",\n };\n}\n\nexport interface A2UIBasicFunctionInfo extends A2UIFunctionPermissions {\n description: string;\n /** The args, as a short TypeScript-like type for the compact schema. */\n parameters: string;\n returnType: A2UIFunctionReturnType;\n /** Built-in functions are value functions of the renderer. */\n allowedCallers: \"rendererOnly\";\n requiresUserActivation?: true;\n /** True for a CopilotKit function that the A2UI basic catalog lacks. */\n extension?: true;\n}\n\n/** Marks a table of built-in functions as callable by the renderer only. */\nfunction rendererOnly<Name extends string>(\n functions: Record<Name, Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>,\n): Readonly<Record<Name, A2UIBasicFunctionInfo>> {\n return Object.fromEntries(\n Object.entries<Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>(\n functions,\n ).map(([name, info]) => [\n name,\n { ...info, allowedCallers: \"rendererOnly\" },\n ]),\n ) as Record<Name, A2UIBasicFunctionInfo>;\n}\n\n/**\n * The basic functions by name. A `{\"@call\"}` in a prop, in an event\n * binding, or in a `callRendererFunction` may name any of them without a\n * declaration in `createGenerativeUI({ functions })`.\n */\nexport const A2UI_BASIC_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n required: {\n description: \"Valid when the value is not empty\",\n parameters: \"{ value: unknown }\",\n returnType: \"validationResult\",\n },\n regex: {\n description: \"Valid when the value matches the pattern\",\n parameters: \"{ value: string; pattern: string }\",\n returnType: \"validationResult\",\n },\n length: {\n description: \"Valid when the length of the value is within min and max\",\n parameters: \"{ value: string; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n numeric: {\n description: \"Valid when the value is a number within min and max\",\n parameters: \"{ value: number; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n email: {\n description: \"Valid when the value is an email address\",\n parameters: \"{ value: string }\",\n returnType: \"validationResult\",\n },\n formatString: {\n description:\n \"Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\\\${ is a literal\",\n parameters: \"{ value: string }\",\n returnType: \"string\",\n },\n formatNumber: {\n description: \"The number in the locale of the user\",\n parameters: \"{ value: number; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatCurrency: {\n description: \"The amount as money, with an ISO 4217 currency code\",\n parameters:\n \"{ value: number; currency: string; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatDate: {\n description:\n 'A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"',\n parameters: \"{ value: string | number; format: string }\",\n returnType: \"string\",\n },\n pluralize: {\n description: \"The string of the plural category of the value\",\n parameters:\n \"{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }\",\n returnType: \"string\",\n },\n openUrl: {\n description: \"Opens an http(s) URL in a new tab. Only from an event\",\n parameters: \"{ url: string }\",\n returnType: \"void\",\n requiresUserActivation: true,\n },\n and: {\n description: \"True when every value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n or: {\n description: \"True when any value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n not: {\n description: \"The negated value\",\n parameters: \"{ value: boolean }\",\n returnType: \"boolean\",\n },\n});\n\n/**\n * The value functions that CopilotKit adds to the basic catalog, because\n * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named\n * args, and `series` builds a computed list. A catalog may declare its own\n * functions in A2UI, so these are regular catalog functions to the model;\n * a renderer without them rejects the call instead of misrendering.\n */\nexport const COPILOTKIT_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n calc: {\n description:\n \"The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name\",\n parameters:\n \"{ expression: string; [name: string]: number | string | boolean }\",\n returnType: \"any\",\n extension: true,\n },\n // WORKAROUND(a2ui-agent-sdk 0.9.0): examples omit `variable` and use default i\n // because the Express compiler mistakes a literal `variable` key for its AST.\n // Runtime support for custom variable names is unchanged.\n // https://github.com/a2ui-project/a2ui/issues/3410\n series: {\n description:\n 'A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.',\n parameters:\n \"{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }\",\n returnType: \"array\",\n extension: true,\n },\n});\n\n/** Every function a `{\"@call\"}` may name without a declaration: basic and CopilotKit. */\nexport const GENERATIVE_UI_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = { ...A2UI_BASIC_FUNCTIONS, ...COPILOTKIT_FUNCTIONS };\n\n/** The name of the system function that gives the index of a template item. */\nexport const A2UI_INDEX_FUNCTION = \"@index\";\n\n/** True for a built-in function name: basic, CopilotKit, or `@index`. */\nexport function isA2UIBasicFunction(name: string) {\n return (\n name === A2UI_INDEX_FUNCTION ||\n Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name)\n );\n}\n\n/**\n * True for a built-in function that a prop or a check may call: every one\n * except the functions that need a user gesture.\n */\nexport function isA2UIValueFunction(name: string) {\n if (name === A2UI_INDEX_FUNCTION) return true;\n const info = Object.prototype.hasOwnProperty.call(\n GENERATIVE_UI_FUNCTIONS,\n name,\n )\n ? GENERATIVE_UI_FUNCTIONS[name]\n : undefined;\n return info !== undefined && !info.requiresUserActivation;\n}\n\n/** `{ \"@call\": \"<name>\", \"args\"?: {...} }`: a function call value. */\nexport function isCallBinding(\n value: unknown,\n): value is { \"@call\": string; args?: Record<string, unknown> } {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>)[\"@call\"] === \"string\"\n );\n}\n\n/** How bad a failed check is. `error` is the default; only an error blocks. */\nexport type A2UIValidationSeverity = \"error\" | \"warning\" | \"info\";\n\n/**\n * A2UI's `ValidationResult`: what a check gives. A validator function gives\n * one; a check may also bind a boolean, which the renderer coerces to one.\n * `code` names the failure for programs; `severity` says how bad it is,\n * `\"error\"` when left out. Other keys are allowed, for app validators that\n * carry more (a suggested value, a field path).\n */\nexport interface A2UIValidationResult {\n valid: boolean;\n message?: string;\n code?: string;\n severity?: A2UIValidationSeverity;\n [extra: string]: unknown;\n}\n\nexport function isValidationResult(\n value: unknown,\n): value is A2UIValidationResult {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>).valid === \"boolean\"\n );\n}\n"],"mappings":";;;;;;;;AAkCA,MAAa,wCACX;;;;;;;;;;;;AAwBF,SAAgB,gBAAgB,IAA6B;AAC3D,KAAI,GAAG,uBAAwB,QAAO;EAAE,UAAU;EAAM,OAAO;EAAO;CACtE,MAAM,UAAU,GAAG,kBAAkB;AACrC,QAAO;EACL,UAAU,YAAY;EACtB,OAAO,YAAY;EACpB;;;AAgBH,SAAS,aACP,WAC+C;AAC/C,QAAO,OAAO,YACZ,OAAO,QACL,UACD,CAAC,KAAK,CAAC,MAAM,UAAU,CACtB,MACA;EAAE,GAAG;EAAM,gBAAgB;EAAgB,CAC5C,CAAC,CACH;;;;;;;AAQH,MAAa,uBAET,aAAa;CACf,UAAU;EACR,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,QAAQ;EACN,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,gBAAgB;EACd,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,YAAY;EACV,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,WAAW;EACT,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACZ,wBAAwB;EACzB;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,IAAI;EACF,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACF,CAAC;;;;;;;;AASF,MAAa,uBAET,aAAa;CACf,MAAM;EACJ,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CAKD,QAAQ;EACN,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CACF,CAAC;;AAGF,MAAa,0BAET;CAAE,GAAG;CAAsB,GAAG;CAAsB;;AAGxD,MAAa,sBAAsB;;AAGnC,SAAgB,oBAAoB,MAAc;AAChD,QACE,SAAS,uBACT,OAAO,UAAU,eAAe,KAAK,yBAAyB,KAAK;;;;;;AAQvE,SAAgB,oBAAoB,MAAc;AAChD,KAAI,SAAS,oBAAqB,QAAO;CACzC,MAAM,OAAO,OAAO,UAAU,eAAe,KAC3C,yBACA,KACD,GACG,wBAAwB,QACxB;AACJ,QAAO,SAAS,UAAa,CAAC,KAAK;;;AAIrC,SAAgB,cACd,OAC8D;AAC9D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,aAAa;;AAsB3D,SAAgB,mBACd,OAC+B;AAC/B,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,UAAU"}
@@ -0,0 +1,108 @@
1
+ //#region src/generative-ui/basic-functions.d.ts
2
+ /**
3
+ * The functions of the A2UI 1.0 basic catalog, as the model and the
4
+ * validator see them. The renderer implements them (react-core
5
+ * `generative-ui/functions.ts`); this file holds only what both sides share:
6
+ * the names, the short signatures for the schema the model reads, and who
7
+ * may call each one.
8
+ */
9
+ /** What a function gives back, as A2UI 1.0 names it. */
10
+ type A2UIFunctionReturnType = "string" | "number" | "boolean" | "array" | "object" | "validationResult" | "any" | "void";
11
+ /**
12
+ * Who may call a function. The renderer calls it from an event binding or
13
+ * as a prop value; the agent calls it with `callRendererFunction`.
14
+ */
15
+ type A2UIAllowedCallers = "rendererOnly" | "agentOnly" | "rendererOrAgent";
16
+ /**
17
+ * The callers of an app function that names none: the renderer only, as
18
+ * in A2UI 1.0. The agent calls a function with `callRendererFunction` only
19
+ * when its declaration allows it (`"rendererOrAgent"` or `"agentOnly"`).
20
+ * The manifests and the exported catalog write the value out.
21
+ */
22
+ declare const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS: A2UIAllowedCallers;
23
+ /** The A2UI 1.0 interface fields of a function: who calls it, and how. */
24
+ interface A2UIFunctionPermissions {
25
+ allowedCallers?: A2UIAllowedCallers;
26
+ /**
27
+ * True for a function that only runs from a user gesture (a click, a key
28
+ * press). It is `rendererOnly`: the agent cannot call it, and a prop
29
+ * cannot be bound to it.
30
+ */
31
+ requiresUserActivation?: boolean;
32
+ }
33
+ /**
34
+ * Who may call a function, from its permissions. A function that needs a
35
+ * user gesture is for the renderer only, whatever `allowedCallers` says.
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * functionCallers({}); // { renderer: true, agent: true }
40
+ * functionCallers({ allowedCallers: "rendererOnly" }); // { renderer: true, agent: false }
41
+ * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }
42
+ * ```
43
+ */
44
+ declare function functionCallers(fn: A2UIFunctionPermissions): {
45
+ renderer: boolean;
46
+ agent: boolean;
47
+ };
48
+ interface A2UIBasicFunctionInfo extends A2UIFunctionPermissions {
49
+ description: string;
50
+ /** The args, as a short TypeScript-like type for the compact schema. */
51
+ parameters: string;
52
+ returnType: A2UIFunctionReturnType;
53
+ /** Built-in functions are value functions of the renderer. */
54
+ allowedCallers: "rendererOnly";
55
+ requiresUserActivation?: true;
56
+ /** True for a CopilotKit function that the A2UI basic catalog lacks. */
57
+ extension?: true;
58
+ }
59
+ /**
60
+ * The basic functions by name. A `{"@call"}` in a prop, in an event
61
+ * binding, or in a `callRendererFunction` may name any of them without a
62
+ * declaration in `createGenerativeUI({ functions })`.
63
+ */
64
+ declare const A2UI_BASIC_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
65
+ /**
66
+ * The value functions that CopilotKit adds to the basic catalog, because
67
+ * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named
68
+ * args, and `series` builds a computed list. A catalog may declare its own
69
+ * functions in A2UI, so these are regular catalog functions to the model;
70
+ * a renderer without them rejects the call instead of misrendering.
71
+ */
72
+ declare const COPILOTKIT_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
73
+ /** Every function a `{"@call"}` may name without a declaration: basic and CopilotKit. */
74
+ declare const GENERATIVE_UI_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
75
+ /** The name of the system function that gives the index of a template item. */
76
+ declare const A2UI_INDEX_FUNCTION = "@index";
77
+ /** True for a built-in function name: basic, CopilotKit, or `@index`. */
78
+ declare function isA2UIBasicFunction(name: string): boolean;
79
+ /**
80
+ * True for a built-in function that a prop or a check may call: every one
81
+ * except the functions that need a user gesture.
82
+ */
83
+ declare function isA2UIValueFunction(name: string): boolean;
84
+ /** `{ "@call": "<name>", "args"?: {...} }`: a function call value. */
85
+ declare function isCallBinding(value: unknown): value is {
86
+ "@call": string;
87
+ args?: Record<string, unknown>;
88
+ };
89
+ /** How bad a failed check is. `error` is the default; only an error blocks. */
90
+ type A2UIValidationSeverity = "error" | "warning" | "info";
91
+ /**
92
+ * A2UI's `ValidationResult`: what a check gives. A validator function gives
93
+ * one; a check may also bind a boolean, which the renderer coerces to one.
94
+ * `code` names the failure for programs; `severity` says how bad it is,
95
+ * `"error"` when left out. Other keys are allowed, for app validators that
96
+ * carry more (a suggested value, a field path).
97
+ */
98
+ interface A2UIValidationResult {
99
+ valid: boolean;
100
+ message?: string;
101
+ code?: string;
102
+ severity?: A2UIValidationSeverity;
103
+ [extra: string]: unknown;
104
+ }
105
+ declare function isValidationResult(value: unknown): value is A2UIValidationResult;
106
+ //#endregion
107
+ export { A2UIAllowedCallers, A2UIBasicFunctionInfo, A2UIFunctionPermissions, A2UIFunctionReturnType, A2UIValidationResult, A2UIValidationSeverity, A2UI_BASIC_FUNCTIONS, A2UI_INDEX_FUNCTION, COPILOTKIT_FUNCTIONS, GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS, GENERATIVE_UI_FUNCTIONS, functionCallers, isA2UIBasicFunction, isA2UIValueFunction, isCallBinding, isValidationResult };
108
+ //# sourceMappingURL=basic-functions.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"basic-functions.d.cts","names":[],"sources":["../../src/generative-ui/basic-functions.ts"],"mappings":";;AASA;;;;;AAcA;;KAdY,sBAAA;;;AAyBZ;;KAXY,kBAAA;;;AAeZ;;;;cAJa,qCAAA,EAAuC,kBAAA;;UAInC,uBAAA;EACf,cAAA,GAAiB,kBAAA;EAMK;AAcxB;;;;EAdE,sBAAA;AAAA;;;;;AAuBF;;;;;;;iBATgB,eAAA,CAAgB,EAAA,EAAI,uBAAA;;;;UASnB,qBAAA,SAA8B,uBAAA;EAC7C,WAAA;EAQS;EANT,UAAA;EACA,UAAA,EAAY,sBAAA;;EAEZ,cAAA;EACA,sBAAA;EAwBiC;EAtBjC,SAAA;AAAA;;;;;;cAsBW,oBAAA,EAAsB,QAAA,CACjC,MAAA,SAAe,qBAAA;;;;;;;;cAsFJ,oBAAA,EAAsB,QAAA,CACjC,MAAA,SAAe,qBAAA;;cAyBJ,uBAAA,EAAyB,QAAA,CACpC,MAAA,SAAe,qBAAA;;cAIJ,mBAAA;AALb;AAAA,iBAQgB,mBAAA,CAAoB,IAAA;;;;;iBAWpB,mBAAA,CAAoB,IAAA;;iBAYpB,aAAA,CACd,KAAA,YACC,KAAA;EAAW,OAAA;EAAiB,IAAA,GAAO,MAAA;AAAA;;KAU1B,sBAAA;;;;;AAnCZ;;;UA4CiB,oBAAA;EACf,KAAA;EACA,OAAA;EACA,IAAA;EACA,QAAA,GAAW,sBAAA;EAAA,CACV,KAAA;AAAA;AAAA,iBAGa,kBAAA,CACd,KAAA,YACC,KAAA,IAAS,oBAAA"}
@@ -0,0 +1,108 @@
1
+ //#region src/generative-ui/basic-functions.d.ts
2
+ /**
3
+ * The functions of the A2UI 1.0 basic catalog, as the model and the
4
+ * validator see them. The renderer implements them (react-core
5
+ * `generative-ui/functions.ts`); this file holds only what both sides share:
6
+ * the names, the short signatures for the schema the model reads, and who
7
+ * may call each one.
8
+ */
9
+ /** What a function gives back, as A2UI 1.0 names it. */
10
+ type A2UIFunctionReturnType = "string" | "number" | "boolean" | "array" | "object" | "validationResult" | "any" | "void";
11
+ /**
12
+ * Who may call a function. The renderer calls it from an event binding or
13
+ * as a prop value; the agent calls it with `callRendererFunction`.
14
+ */
15
+ type A2UIAllowedCallers = "rendererOnly" | "agentOnly" | "rendererOrAgent";
16
+ /**
17
+ * The callers of an app function that names none: the renderer only, as
18
+ * in A2UI 1.0. The agent calls a function with `callRendererFunction` only
19
+ * when its declaration allows it (`"rendererOrAgent"` or `"agentOnly"`).
20
+ * The manifests and the exported catalog write the value out.
21
+ */
22
+ declare const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS: A2UIAllowedCallers;
23
+ /** The A2UI 1.0 interface fields of a function: who calls it, and how. */
24
+ interface A2UIFunctionPermissions {
25
+ allowedCallers?: A2UIAllowedCallers;
26
+ /**
27
+ * True for a function that only runs from a user gesture (a click, a key
28
+ * press). It is `rendererOnly`: the agent cannot call it, and a prop
29
+ * cannot be bound to it.
30
+ */
31
+ requiresUserActivation?: boolean;
32
+ }
33
+ /**
34
+ * Who may call a function, from its permissions. A function that needs a
35
+ * user gesture is for the renderer only, whatever `allowedCallers` says.
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * functionCallers({}); // { renderer: true, agent: true }
40
+ * functionCallers({ allowedCallers: "rendererOnly" }); // { renderer: true, agent: false }
41
+ * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }
42
+ * ```
43
+ */
44
+ declare function functionCallers(fn: A2UIFunctionPermissions): {
45
+ renderer: boolean;
46
+ agent: boolean;
47
+ };
48
+ interface A2UIBasicFunctionInfo extends A2UIFunctionPermissions {
49
+ description: string;
50
+ /** The args, as a short TypeScript-like type for the compact schema. */
51
+ parameters: string;
52
+ returnType: A2UIFunctionReturnType;
53
+ /** Built-in functions are value functions of the renderer. */
54
+ allowedCallers: "rendererOnly";
55
+ requiresUserActivation?: true;
56
+ /** True for a CopilotKit function that the A2UI basic catalog lacks. */
57
+ extension?: true;
58
+ }
59
+ /**
60
+ * The basic functions by name. A `{"@call"}` in a prop, in an event
61
+ * binding, or in a `callRendererFunction` may name any of them without a
62
+ * declaration in `createGenerativeUI({ functions })`.
63
+ */
64
+ declare const A2UI_BASIC_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
65
+ /**
66
+ * The value functions that CopilotKit adds to the basic catalog, because
67
+ * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named
68
+ * args, and `series` builds a computed list. A catalog may declare its own
69
+ * functions in A2UI, so these are regular catalog functions to the model;
70
+ * a renderer without them rejects the call instead of misrendering.
71
+ */
72
+ declare const COPILOTKIT_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
73
+ /** Every function a `{"@call"}` may name without a declaration: basic and CopilotKit. */
74
+ declare const GENERATIVE_UI_FUNCTIONS: Readonly<Record<string, A2UIBasicFunctionInfo>>;
75
+ /** The name of the system function that gives the index of a template item. */
76
+ declare const A2UI_INDEX_FUNCTION = "@index";
77
+ /** True for a built-in function name: basic, CopilotKit, or `@index`. */
78
+ declare function isA2UIBasicFunction(name: string): boolean;
79
+ /**
80
+ * True for a built-in function that a prop or a check may call: every one
81
+ * except the functions that need a user gesture.
82
+ */
83
+ declare function isA2UIValueFunction(name: string): boolean;
84
+ /** `{ "@call": "<name>", "args"?: {...} }`: a function call value. */
85
+ declare function isCallBinding(value: unknown): value is {
86
+ "@call": string;
87
+ args?: Record<string, unknown>;
88
+ };
89
+ /** How bad a failed check is. `error` is the default; only an error blocks. */
90
+ type A2UIValidationSeverity = "error" | "warning" | "info";
91
+ /**
92
+ * A2UI's `ValidationResult`: what a check gives. A validator function gives
93
+ * one; a check may also bind a boolean, which the renderer coerces to one.
94
+ * `code` names the failure for programs; `severity` says how bad it is,
95
+ * `"error"` when left out. Other keys are allowed, for app validators that
96
+ * carry more (a suggested value, a field path).
97
+ */
98
+ interface A2UIValidationResult {
99
+ valid: boolean;
100
+ message?: string;
101
+ code?: string;
102
+ severity?: A2UIValidationSeverity;
103
+ [extra: string]: unknown;
104
+ }
105
+ declare function isValidationResult(value: unknown): value is A2UIValidationResult;
106
+ //#endregion
107
+ export { A2UIAllowedCallers, A2UIBasicFunctionInfo, A2UIFunctionPermissions, A2UIFunctionReturnType, A2UIValidationResult, A2UIValidationSeverity, A2UI_BASIC_FUNCTIONS, A2UI_INDEX_FUNCTION, COPILOTKIT_FUNCTIONS, GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS, GENERATIVE_UI_FUNCTIONS, functionCallers, isA2UIBasicFunction, isA2UIValueFunction, isCallBinding, isValidationResult };
108
+ //# sourceMappingURL=basic-functions.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"basic-functions.d.mts","names":[],"sources":["../../src/generative-ui/basic-functions.ts"],"mappings":";;AASA;;;;;AAcA;;KAdY,sBAAA;;;AAyBZ;;KAXY,kBAAA;;;AAeZ;;;;cAJa,qCAAA,EAAuC,kBAAA;;UAInC,uBAAA;EACf,cAAA,GAAiB,kBAAA;EAMK;AAcxB;;;;EAdE,sBAAA;AAAA;;;;;AAuBF;;;;;;;iBATgB,eAAA,CAAgB,EAAA,EAAI,uBAAA;;;;UASnB,qBAAA,SAA8B,uBAAA;EAC7C,WAAA;EAQS;EANT,UAAA;EACA,UAAA,EAAY,sBAAA;;EAEZ,cAAA;EACA,sBAAA;EAwBiC;EAtBjC,SAAA;AAAA;;;;;;cAsBW,oBAAA,EAAsB,QAAA,CACjC,MAAA,SAAe,qBAAA;;;;;;;;cAsFJ,oBAAA,EAAsB,QAAA,CACjC,MAAA,SAAe,qBAAA;;cAyBJ,uBAAA,EAAyB,QAAA,CACpC,MAAA,SAAe,qBAAA;;cAIJ,mBAAA;AALb;AAAA,iBAQgB,mBAAA,CAAoB,IAAA;;;;;iBAWpB,mBAAA,CAAoB,IAAA;;iBAYpB,aAAA,CACd,KAAA,YACC,KAAA;EAAW,OAAA;EAAiB,IAAA,GAAO,MAAA;AAAA;;KAU1B,sBAAA;;;;;AAnCZ;;;UA4CiB,oBAAA;EACf,KAAA;EACA,OAAA;EACA,IAAA;EACA,QAAA,GAAW,sBAAA;EAAA,CACV,KAAA;AAAA;AAAA,iBAGa,kBAAA,CACd,KAAA,YACC,KAAA,IAAS,oBAAA"}
@@ -0,0 +1,167 @@
1
+ //#region src/generative-ui/basic-functions.ts
2
+ /**
3
+ * The callers of an app function that names none: the renderer only, as
4
+ * in A2UI 1.0. The agent calls a function with `callRendererFunction` only
5
+ * when its declaration allows it (`"rendererOrAgent"` or `"agentOnly"`).
6
+ * The manifests and the exported catalog write the value out.
7
+ */
8
+ const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS = "rendererOnly";
9
+ /**
10
+ * Who may call a function, from its permissions. A function that needs a
11
+ * user gesture is for the renderer only, whatever `allowedCallers` says.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * functionCallers({}); // { renderer: true, agent: true }
16
+ * functionCallers({ allowedCallers: "rendererOnly" }); // { renderer: true, agent: false }
17
+ * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }
18
+ * ```
19
+ */
20
+ function functionCallers(fn) {
21
+ if (fn.requiresUserActivation) return {
22
+ renderer: true,
23
+ agent: false
24
+ };
25
+ const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;
26
+ return {
27
+ renderer: callers !== "agentOnly",
28
+ agent: callers !== "rendererOnly"
29
+ };
30
+ }
31
+ /** Marks a table of built-in functions as callable by the renderer only. */
32
+ function rendererOnly(functions) {
33
+ return Object.fromEntries(Object.entries(functions).map(([name, info]) => [name, {
34
+ ...info,
35
+ allowedCallers: "rendererOnly"
36
+ }]));
37
+ }
38
+ /**
39
+ * The basic functions by name. A `{"@call"}` in a prop, in an event
40
+ * binding, or in a `callRendererFunction` may name any of them without a
41
+ * declaration in `createGenerativeUI({ functions })`.
42
+ */
43
+ const A2UI_BASIC_FUNCTIONS = rendererOnly({
44
+ required: {
45
+ description: "Valid when the value is not empty",
46
+ parameters: "{ value: unknown }",
47
+ returnType: "validationResult"
48
+ },
49
+ regex: {
50
+ description: "Valid when the value matches the pattern",
51
+ parameters: "{ value: string; pattern: string }",
52
+ returnType: "validationResult"
53
+ },
54
+ length: {
55
+ description: "Valid when the length of the value is within min and max",
56
+ parameters: "{ value: string; min?: number; max?: number }",
57
+ returnType: "validationResult"
58
+ },
59
+ numeric: {
60
+ description: "Valid when the value is a number within min and max",
61
+ parameters: "{ value: number; min?: number; max?: number }",
62
+ returnType: "validationResult"
63
+ },
64
+ email: {
65
+ description: "Valid when the value is an email address",
66
+ parameters: "{ value: string }",
67
+ returnType: "validationResult"
68
+ },
69
+ formatString: {
70
+ description: "Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\${ is a literal",
71
+ parameters: "{ value: string }",
72
+ returnType: "string"
73
+ },
74
+ formatNumber: {
75
+ description: "The number in the locale of the user",
76
+ parameters: "{ value: number; decimals?: number; grouping?: boolean }",
77
+ returnType: "string"
78
+ },
79
+ formatCurrency: {
80
+ description: "The amount as money, with an ISO 4217 currency code",
81
+ parameters: "{ value: number; currency: string; decimals?: number; grouping?: boolean }",
82
+ returnType: "string"
83
+ },
84
+ formatDate: {
85
+ description: "A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"",
86
+ parameters: "{ value: string | number; format: string }",
87
+ returnType: "string"
88
+ },
89
+ pluralize: {
90
+ description: "The string of the plural category of the value",
91
+ parameters: "{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }",
92
+ returnType: "string"
93
+ },
94
+ openUrl: {
95
+ description: "Opens an http(s) URL in a new tab. Only from an event",
96
+ parameters: "{ url: string }",
97
+ returnType: "void",
98
+ requiresUserActivation: true
99
+ },
100
+ and: {
101
+ description: "True when every value is true",
102
+ parameters: "{ values: boolean[] }",
103
+ returnType: "boolean"
104
+ },
105
+ or: {
106
+ description: "True when any value is true",
107
+ parameters: "{ values: boolean[] }",
108
+ returnType: "boolean"
109
+ },
110
+ not: {
111
+ description: "The negated value",
112
+ parameters: "{ value: boolean }",
113
+ returnType: "boolean"
114
+ }
115
+ });
116
+ /**
117
+ * The value functions that CopilotKit adds to the basic catalog, because
118
+ * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named
119
+ * args, and `series` builds a computed list. A catalog may declare its own
120
+ * functions in A2UI, so these are regular catalog functions to the model;
121
+ * a renderer without them rejects the call instead of misrendering.
122
+ */
123
+ const COPILOTKIT_FUNCTIONS = rendererOnly({
124
+ calc: {
125
+ description: "The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name",
126
+ parameters: "{ expression: string; [name: string]: number | string | boolean }",
127
+ returnType: "any",
128
+ extension: true
129
+ },
130
+ series: {
131
+ description: "A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.",
132
+ parameters: "{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }",
133
+ returnType: "array",
134
+ extension: true
135
+ }
136
+ });
137
+ /** Every function a `{"@call"}` may name without a declaration: basic and CopilotKit. */
138
+ const GENERATIVE_UI_FUNCTIONS = {
139
+ ...A2UI_BASIC_FUNCTIONS,
140
+ ...COPILOTKIT_FUNCTIONS
141
+ };
142
+ /** The name of the system function that gives the index of a template item. */
143
+ const A2UI_INDEX_FUNCTION = "@index";
144
+ /** True for a built-in function name: basic, CopilotKit, or `@index`. */
145
+ function isA2UIBasicFunction(name) {
146
+ return name === A2UI_INDEX_FUNCTION || Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name);
147
+ }
148
+ /**
149
+ * True for a built-in function that a prop or a check may call: every one
150
+ * except the functions that need a user gesture.
151
+ */
152
+ function isA2UIValueFunction(name) {
153
+ if (name === A2UI_INDEX_FUNCTION) return true;
154
+ const info = Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name) ? GENERATIVE_UI_FUNCTIONS[name] : void 0;
155
+ return info !== void 0 && !info.requiresUserActivation;
156
+ }
157
+ /** `{ "@call": "<name>", "args"?: {...} }`: a function call value. */
158
+ function isCallBinding(value) {
159
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value["@call"] === "string";
160
+ }
161
+ function isValidationResult(value) {
162
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.valid === "boolean";
163
+ }
164
+
165
+ //#endregion
166
+ export { A2UI_BASIC_FUNCTIONS, A2UI_INDEX_FUNCTION, COPILOTKIT_FUNCTIONS, GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS, GENERATIVE_UI_FUNCTIONS, functionCallers, isA2UIBasicFunction, isA2UIValueFunction, isCallBinding, isValidationResult };
167
+ //# sourceMappingURL=basic-functions.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"basic-functions.mjs","names":[],"sources":["../../src/generative-ui/basic-functions.ts"],"sourcesContent":["/**\n * The functions of the A2UI 1.0 basic catalog, as the model and the\n * validator see them. The renderer implements them (react-core\n * `generative-ui/functions.ts`); this file holds only what both sides share:\n * the names, the short signatures for the schema the model reads, and who\n * may call each one.\n */\n\n/** What a function gives back, as A2UI 1.0 names it. */\nexport type A2UIFunctionReturnType =\n | \"string\"\n | \"number\"\n | \"boolean\"\n | \"array\"\n | \"object\"\n | \"validationResult\"\n | \"any\"\n | \"void\";\n\n/**\n * Who may call a function. The renderer calls it from an event binding or\n * as a prop value; the agent calls it with `callRendererFunction`.\n */\nexport type A2UIAllowedCallers =\n | \"rendererOnly\"\n | \"agentOnly\"\n | \"rendererOrAgent\";\n\n/**\n * The callers of an app function that names none: the renderer only, as\n * in A2UI 1.0. The agent calls a function with `callRendererFunction` only\n * when its declaration allows it (`\"rendererOrAgent\"` or `\"agentOnly\"`).\n * The manifests and the exported catalog write the value out.\n */\nexport const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS: A2UIAllowedCallers =\n \"rendererOnly\";\n\n/** The A2UI 1.0 interface fields of a function: who calls it, and how. */\nexport interface A2UIFunctionPermissions {\n allowedCallers?: A2UIAllowedCallers;\n /**\n * True for a function that only runs from a user gesture (a click, a key\n * press). It is `rendererOnly`: the agent cannot call it, and a prop\n * cannot be bound to it.\n */\n requiresUserActivation?: boolean;\n}\n\n/**\n * Who may call a function, from its permissions. A function that needs a\n * user gesture is for the renderer only, whatever `allowedCallers` says.\n *\n * @example\n * ```ts\n * functionCallers({}); // { renderer: true, agent: true }\n * functionCallers({ allowedCallers: \"rendererOnly\" }); // { renderer: true, agent: false }\n * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }\n * ```\n */\nexport function functionCallers(fn: A2UIFunctionPermissions) {\n if (fn.requiresUserActivation) return { renderer: true, agent: false };\n const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;\n return {\n renderer: callers !== \"agentOnly\",\n agent: callers !== \"rendererOnly\",\n };\n}\n\nexport interface A2UIBasicFunctionInfo extends A2UIFunctionPermissions {\n description: string;\n /** The args, as a short TypeScript-like type for the compact schema. */\n parameters: string;\n returnType: A2UIFunctionReturnType;\n /** Built-in functions are value functions of the renderer. */\n allowedCallers: \"rendererOnly\";\n requiresUserActivation?: true;\n /** True for a CopilotKit function that the A2UI basic catalog lacks. */\n extension?: true;\n}\n\n/** Marks a table of built-in functions as callable by the renderer only. */\nfunction rendererOnly<Name extends string>(\n functions: Record<Name, Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>,\n): Readonly<Record<Name, A2UIBasicFunctionInfo>> {\n return Object.fromEntries(\n Object.entries<Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>(\n functions,\n ).map(([name, info]) => [\n name,\n { ...info, allowedCallers: \"rendererOnly\" },\n ]),\n ) as Record<Name, A2UIBasicFunctionInfo>;\n}\n\n/**\n * The basic functions by name. A `{\"@call\"}` in a prop, in an event\n * binding, or in a `callRendererFunction` may name any of them without a\n * declaration in `createGenerativeUI({ functions })`.\n */\nexport const A2UI_BASIC_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n required: {\n description: \"Valid when the value is not empty\",\n parameters: \"{ value: unknown }\",\n returnType: \"validationResult\",\n },\n regex: {\n description: \"Valid when the value matches the pattern\",\n parameters: \"{ value: string; pattern: string }\",\n returnType: \"validationResult\",\n },\n length: {\n description: \"Valid when the length of the value is within min and max\",\n parameters: \"{ value: string; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n numeric: {\n description: \"Valid when the value is a number within min and max\",\n parameters: \"{ value: number; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n email: {\n description: \"Valid when the value is an email address\",\n parameters: \"{ value: string }\",\n returnType: \"validationResult\",\n },\n formatString: {\n description:\n \"Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\\\${ is a literal\",\n parameters: \"{ value: string }\",\n returnType: \"string\",\n },\n formatNumber: {\n description: \"The number in the locale of the user\",\n parameters: \"{ value: number; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatCurrency: {\n description: \"The amount as money, with an ISO 4217 currency code\",\n parameters:\n \"{ value: number; currency: string; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatDate: {\n description:\n 'A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"',\n parameters: \"{ value: string | number; format: string }\",\n returnType: \"string\",\n },\n pluralize: {\n description: \"The string of the plural category of the value\",\n parameters:\n \"{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }\",\n returnType: \"string\",\n },\n openUrl: {\n description: \"Opens an http(s) URL in a new tab. Only from an event\",\n parameters: \"{ url: string }\",\n returnType: \"void\",\n requiresUserActivation: true,\n },\n and: {\n description: \"True when every value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n or: {\n description: \"True when any value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n not: {\n description: \"The negated value\",\n parameters: \"{ value: boolean }\",\n returnType: \"boolean\",\n },\n});\n\n/**\n * The value functions that CopilotKit adds to the basic catalog, because\n * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named\n * args, and `series` builds a computed list. A catalog may declare its own\n * functions in A2UI, so these are regular catalog functions to the model;\n * a renderer without them rejects the call instead of misrendering.\n */\nexport const COPILOTKIT_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n calc: {\n description:\n \"The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name\",\n parameters:\n \"{ expression: string; [name: string]: number | string | boolean }\",\n returnType: \"any\",\n extension: true,\n },\n // WORKAROUND(a2ui-agent-sdk 0.9.0): examples omit `variable` and use default i\n // because the Express compiler mistakes a literal `variable` key for its AST.\n // Runtime support for custom variable names is unchanged.\n // https://github.com/a2ui-project/a2ui/issues/3410\n series: {\n description:\n 'A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.',\n parameters:\n \"{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }\",\n returnType: \"array\",\n extension: true,\n },\n});\n\n/** Every function a `{\"@call\"}` may name without a declaration: basic and CopilotKit. */\nexport const GENERATIVE_UI_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = { ...A2UI_BASIC_FUNCTIONS, ...COPILOTKIT_FUNCTIONS };\n\n/** The name of the system function that gives the index of a template item. */\nexport const A2UI_INDEX_FUNCTION = \"@index\";\n\n/** True for a built-in function name: basic, CopilotKit, or `@index`. */\nexport function isA2UIBasicFunction(name: string) {\n return (\n name === A2UI_INDEX_FUNCTION ||\n Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name)\n );\n}\n\n/**\n * True for a built-in function that a prop or a check may call: every one\n * except the functions that need a user gesture.\n */\nexport function isA2UIValueFunction(name: string) {\n if (name === A2UI_INDEX_FUNCTION) return true;\n const info = Object.prototype.hasOwnProperty.call(\n GENERATIVE_UI_FUNCTIONS,\n name,\n )\n ? GENERATIVE_UI_FUNCTIONS[name]\n : undefined;\n return info !== undefined && !info.requiresUserActivation;\n}\n\n/** `{ \"@call\": \"<name>\", \"args\"?: {...} }`: a function call value. */\nexport function isCallBinding(\n value: unknown,\n): value is { \"@call\": string; args?: Record<string, unknown> } {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>)[\"@call\"] === \"string\"\n );\n}\n\n/** How bad a failed check is. `error` is the default; only an error blocks. */\nexport type A2UIValidationSeverity = \"error\" | \"warning\" | \"info\";\n\n/**\n * A2UI's `ValidationResult`: what a check gives. A validator function gives\n * one; a check may also bind a boolean, which the renderer coerces to one.\n * `code` names the failure for programs; `severity` says how bad it is,\n * `\"error\"` when left out. Other keys are allowed, for app validators that\n * carry more (a suggested value, a field path).\n */\nexport interface A2UIValidationResult {\n valid: boolean;\n message?: string;\n code?: string;\n severity?: A2UIValidationSeverity;\n [extra: string]: unknown;\n}\n\nexport function isValidationResult(\n value: unknown,\n): value is A2UIValidationResult {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>).valid === \"boolean\"\n );\n}\n"],"mappings":";;;;;;;AAkCA,MAAa,wCACX;;;;;;;;;;;;AAwBF,SAAgB,gBAAgB,IAA6B;AAC3D,KAAI,GAAG,uBAAwB,QAAO;EAAE,UAAU;EAAM,OAAO;EAAO;CACtE,MAAM,UAAU,GAAG,kBAAkB;AACrC,QAAO;EACL,UAAU,YAAY;EACtB,OAAO,YAAY;EACpB;;;AAgBH,SAAS,aACP,WAC+C;AAC/C,QAAO,OAAO,YACZ,OAAO,QACL,UACD,CAAC,KAAK,CAAC,MAAM,UAAU,CACtB,MACA;EAAE,GAAG;EAAM,gBAAgB;EAAgB,CAC5C,CAAC,CACH;;;;;;;AAQH,MAAa,uBAET,aAAa;CACf,UAAU;EACR,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,QAAQ;EACN,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,gBAAgB;EACd,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,YAAY;EACV,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,WAAW;EACT,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACZ,wBAAwB;EACzB;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,IAAI;EACF,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACF,CAAC;;;;;;;;AASF,MAAa,uBAET,aAAa;CACf,MAAM;EACJ,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CAKD,QAAQ;EACN,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CACF,CAAC;;AAGF,MAAa,0BAET;CAAE,GAAG;CAAsB,GAAG;CAAsB;;AAGxD,MAAa,sBAAsB;;AAGnC,SAAgB,oBAAoB,MAAc;AAChD,QACE,SAAS,uBACT,OAAO,UAAU,eAAe,KAAK,yBAAyB,KAAK;;;;;;AAQvE,SAAgB,oBAAoB,MAAc;AAChD,KAAI,SAAS,oBAAqB,QAAO;CACzC,MAAM,OAAO,OAAO,UAAU,eAAe,KAC3C,yBACA,KACD,GACG,wBAAwB,QACxB;AACJ,QAAO,SAAS,UAAa,CAAC,KAAK;;;AAIrC,SAAgB,cACd,OAC8D;AAC9D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,aAAa;;AAsB3D,SAAgB,mBACd,OAC+B;AAC/B,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,UAAU"}