@heroui/agent 0.2.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +64 -0
- package/LICENSE +21 -0
- package/README.md +205 -0
- package/dist/chart-content-VZ66GD22.js +1391 -0
- package/dist/chunk-3FG5NRTX.js +9 -0
- package/dist/chunk-CU6MPKAJ.js +359 -0
- package/dist/chunk-DW4AQRM5.js +297 -0
- package/dist/chunk-GDDNN2XY.js +954 -0
- package/dist/chunk-RQCTC4JB.js +1084 -0
- package/dist/chunk-TOOT6SZ2.js +74 -0
- package/dist/chunk-VJA52U5P.js +137 -0
- package/dist/component-renderer-IBJDNXSO.js +9780 -0
- package/dist/contracts.d.ts +1293 -0
- package/dist/contracts.js +2325 -0
- package/dist/css/index.css +2 -0
- package/dist/embed-runtime-XOPQY7Z5.js +7254 -0
- package/dist/identity-NYCXY1mT.d.ts +164 -0
- package/dist/index.d.ts +594 -0
- package/dist/index.js +28 -0
- package/dist/interactive-map-surface-67KHT3VB.js +362 -0
- package/dist/next.d.ts +4 -0
- package/dist/next.js +22 -0
- package/dist/server.d.ts +31 -0
- package/dist/server.js +256 -0
- package/package.json +133 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,594 @@
|
|
|
1
|
+
import { ComponentType, ReactNode, CSSProperties } from 'react';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
import { AnimateOptions, CustomRenderer, CustomRendererProps } from 'streamdown';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Deliberately Zod-free: `createToolHelper` and these types are re-exported from
|
|
7
|
+
* the package root, which the panel shell is served from. The manifest
|
|
8
|
+
* serializer that does need Zod lives in `./client-tools-manifest`.
|
|
9
|
+
*/
|
|
10
|
+
type ClientToolStatus = "input-streaming" | "approval-requested" | "executing" | "completed" | "rejected" | "error";
|
|
11
|
+
type ClientToolIconProps = {
|
|
12
|
+
color?: string;
|
|
13
|
+
size?: number | string;
|
|
14
|
+
stroke?: number | string;
|
|
15
|
+
};
|
|
16
|
+
type ClientToolRenderProps<TArgs = unknown> = {
|
|
17
|
+
/** Arguments the agent passed to the tool (typed when using Zod). */
|
|
18
|
+
args: TArgs;
|
|
19
|
+
/** Error message, present when `status === "error"`. */
|
|
20
|
+
error?: string;
|
|
21
|
+
/** Approve the call. Present when `status === "approval-requested"`. */
|
|
22
|
+
onApprove?: () => void;
|
|
23
|
+
/** Reject the call. Present when `status === "approval-requested"`. */
|
|
24
|
+
onReject?: () => void;
|
|
25
|
+
/** Return value of `execute`, present when `status === "completed"`. */
|
|
26
|
+
result?: unknown;
|
|
27
|
+
status: ClientToolStatus;
|
|
28
|
+
};
|
|
29
|
+
type ClientToolSchema<TArgs> = {
|
|
30
|
+
parse: (input: unknown) => TArgs;
|
|
31
|
+
safeParse: (input: unknown) => unknown;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* A tool the agent can call in the user's browser. Execution and rendering
|
|
35
|
+
* never leave the page — only the name, description, schema, and approval
|
|
36
|
+
* flag are shared with the hosted agent.
|
|
37
|
+
*/
|
|
38
|
+
type ClientTool<TArgs = any, TContext = any> = {
|
|
39
|
+
description: string;
|
|
40
|
+
/** Human-readable name shown in the default tool card. Defaults to `name`. */
|
|
41
|
+
displayName?: string;
|
|
42
|
+
execute: (args: TArgs, context: TContext) => Promise<unknown> | unknown;
|
|
43
|
+
/** Icon component for the default tool card ({size, color, stroke} props). */
|
|
44
|
+
icon?: ComponentType<ClientToolIconProps>;
|
|
45
|
+
iconColor?: string;
|
|
46
|
+
name: string;
|
|
47
|
+
/** When true, the user must approve the call before `execute` runs. */
|
|
48
|
+
needsApproval?: boolean;
|
|
49
|
+
/** Zod schema (typed) or raw JSON Schema object for the tool parameters. */
|
|
50
|
+
parameters: ClientToolSchema<TArgs> | Record<string, unknown>;
|
|
51
|
+
/**
|
|
52
|
+
* Replace the default tool card. Return `null` for any status to fall back
|
|
53
|
+
* to the default card for that state.
|
|
54
|
+
*/
|
|
55
|
+
render?: (props: ClientToolRenderProps<TArgs>) => ReactNode;
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Returns a type-safe tool factory bound to your shared context type:
|
|
59
|
+
*
|
|
60
|
+
* ```ts
|
|
61
|
+
* type AppContext = {apiClient: ApiClient};
|
|
62
|
+
* const tool = createToolHelper<AppContext>();
|
|
63
|
+
* const tools = [tool({name: "search_users", parameters: z.object({...}), execute: (args, ctx) => ...})];
|
|
64
|
+
* ```
|
|
65
|
+
*/
|
|
66
|
+
declare function createToolHelper<TContext>(): <TArgs>(definition: ClientTool<TArgs, TContext>) => ClientTool<TArgs, TContext>;
|
|
67
|
+
|
|
68
|
+
type MessageActionKind = "copy" | "feedback" | "retry";
|
|
69
|
+
type MessageFeedbackReason = "did_not_follow_instructions" | "incomplete" | "incorrect" | "not_relevant" | "other" | "unclear";
|
|
70
|
+
|
|
71
|
+
/** How browser client-tool calls are approved before they execute. */
|
|
72
|
+
type AgentPermissionMode$1 = "ask" | "auto" | "full";
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* File types that the hosted model pipeline can process consistently.
|
|
76
|
+
*
|
|
77
|
+
* SVG and office/archive formats are intentionally excluded: SVG can carry
|
|
78
|
+
* active content, while provider support for zipped document formats varies.
|
|
79
|
+
*/
|
|
80
|
+
declare const HEROUI_AGENT_ATTACHMENT_EXTENSION_BY_CONTENT_TYPE: {
|
|
81
|
+
readonly "application/json": "json";
|
|
82
|
+
readonly "application/pdf": "pdf";
|
|
83
|
+
readonly "image/gif": "gif";
|
|
84
|
+
readonly "image/jpeg": "jpg";
|
|
85
|
+
readonly "image/png": "png";
|
|
86
|
+
readonly "image/webp": "webp";
|
|
87
|
+
readonly "text/csv": "csv";
|
|
88
|
+
readonly "text/markdown": "md";
|
|
89
|
+
readonly "text/plain": "txt";
|
|
90
|
+
readonly "text/tab-separated-values": "tsv";
|
|
91
|
+
};
|
|
92
|
+
type HeroUIAgentAttachmentContentType = keyof typeof HEROUI_AGENT_ATTACHMENT_EXTENSION_BY_CONTENT_TYPE;
|
|
93
|
+
|
|
94
|
+
declare const agentThemeSchema: z.ZodEnum<{
|
|
95
|
+
dark: "dark";
|
|
96
|
+
light: "light";
|
|
97
|
+
system: "system";
|
|
98
|
+
}>;
|
|
99
|
+
type AgentTheme = z.infer<typeof agentThemeSchema>;
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Deliberately Zod-free: the model catalogue is re-exported from the package
|
|
103
|
+
* root, so importing Zod here would pull the whole validation library into the
|
|
104
|
+
* panel shell's first-paint graph. The matching schema lives in
|
|
105
|
+
* `./models.schema`, which only server and contract consumers need.
|
|
106
|
+
*/
|
|
107
|
+
/** Model ids the hosted agent accepts from the browser picker. */
|
|
108
|
+
declare const AGENT_MODEL_IDS: readonly ["moonshotai/Kimi-K3", "openai/gpt-5.6-luna", "openai/gpt-5.6-terra", "openai/gpt-5.6-sol", "google/gemini-3.6-flash", "anthropic/claude-sonnet-5", "anthropic/claude-opus-4.8"];
|
|
109
|
+
type AgentModelId = (typeof AGENT_MODEL_IDS)[number];
|
|
110
|
+
/**
|
|
111
|
+
* Retired ids mapped to their replacement. Model ids are a public part of the
|
|
112
|
+
* embed API — a customer pins one in their own code and projects store one as
|
|
113
|
+
* their default — so a retired id keeps resolving instead of failing the
|
|
114
|
+
* session with an "Invalid agent model" error.
|
|
115
|
+
*/
|
|
116
|
+
declare const LEGACY_AGENT_MODEL_IDS: Record<string, AgentModelId>;
|
|
117
|
+
/** Resolves a possibly-retired model id to the id the runtime should use. */
|
|
118
|
+
declare function resolveAgentModelId(value: string): string;
|
|
119
|
+
type AgentModelTier = "codegen" | "complex" | "light";
|
|
120
|
+
type AgentModelOption = {
|
|
121
|
+
description: string;
|
|
122
|
+
id: AgentModelId;
|
|
123
|
+
label: string;
|
|
124
|
+
provider: "Anthropic" | "Google" | "Moonshot AI" | "OpenAI";
|
|
125
|
+
tier: AgentModelTier;
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* Recommended default selected when the optional picker first opens. Luna
|
|
129
|
+
* matches the hosted runtime's baked-in default (`DEFAULT_CHAT_MODEL_IDS.herouiAgent`),
|
|
130
|
+
* so what users see in the picker is what actually runs by default.
|
|
131
|
+
*/
|
|
132
|
+
declare const DEFAULT_AGENT_PICKER_MODEL_ID = "openai/gpt-5.6-luna";
|
|
133
|
+
/**
|
|
134
|
+
* Small, tool-capable model catalog for HeroUI Agent. These ids are the
|
|
135
|
+
* server-side allowlist as well as the browser picker source of truth.
|
|
136
|
+
*/
|
|
137
|
+
declare const AGENT_MODEL_OPTIONS: readonly [{
|
|
138
|
+
readonly description: "Flagship model for coding, reasoning, and knowledge work";
|
|
139
|
+
readonly id: "moonshotai/Kimi-K3";
|
|
140
|
+
readonly label: "Kimi K3";
|
|
141
|
+
readonly provider: "Moonshot AI";
|
|
142
|
+
readonly tier: "light";
|
|
143
|
+
}, {
|
|
144
|
+
readonly description: "Fast answers and lightweight agent workflows";
|
|
145
|
+
readonly id: "openai/gpt-5.6-luna";
|
|
146
|
+
readonly label: "GPT-5.6 Luna";
|
|
147
|
+
readonly provider: "OpenAI";
|
|
148
|
+
readonly tier: "light";
|
|
149
|
+
}, {
|
|
150
|
+
readonly description: "Balanced reasoning for everyday agent tasks";
|
|
151
|
+
readonly id: "openai/gpt-5.6-terra";
|
|
152
|
+
readonly label: "GPT-5.6 Terra";
|
|
153
|
+
readonly provider: "OpenAI";
|
|
154
|
+
readonly tier: "codegen";
|
|
155
|
+
}, {
|
|
156
|
+
readonly description: "Deep reasoning for complex, multi-step analysis";
|
|
157
|
+
readonly id: "openai/gpt-5.6-sol";
|
|
158
|
+
readonly label: "GPT-5.6 Sol";
|
|
159
|
+
readonly provider: "OpenAI";
|
|
160
|
+
readonly tier: "complex";
|
|
161
|
+
}, {
|
|
162
|
+
readonly description: "Fast multimodal analysis with a large context window";
|
|
163
|
+
readonly id: "google/gemini-3.6-flash";
|
|
164
|
+
readonly label: "Gemini 3.6 Flash";
|
|
165
|
+
readonly provider: "Google";
|
|
166
|
+
readonly tier: "light";
|
|
167
|
+
}, {
|
|
168
|
+
readonly description: "Strong agentic reasoning and polished UI decisions";
|
|
169
|
+
readonly id: "anthropic/claude-sonnet-5";
|
|
170
|
+
readonly label: "Claude Sonnet 5";
|
|
171
|
+
readonly provider: "Anthropic";
|
|
172
|
+
readonly tier: "codegen";
|
|
173
|
+
}, {
|
|
174
|
+
readonly description: "Highest-capability Claude for difficult research and analysis";
|
|
175
|
+
readonly id: "anthropic/claude-opus-4.8";
|
|
176
|
+
readonly label: "Claude Opus 4.8";
|
|
177
|
+
readonly provider: "Anthropic";
|
|
178
|
+
readonly tier: "complex";
|
|
179
|
+
}];
|
|
180
|
+
declare function isAgentModelId(value: unknown): value is AgentModelId;
|
|
181
|
+
/** Unknown/env-overridden models keep the hosted agent's historical light tier. */
|
|
182
|
+
declare function getAgentModelTier(modelId?: string): AgentModelTier;
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Light/dark color scheme selection for the embed. `"system"` follows the
|
|
186
|
+
* OS preference and updates live when it changes.
|
|
187
|
+
*/
|
|
188
|
+
type AgentColorScheme = AgentTheme;
|
|
189
|
+
/**
|
|
190
|
+
* A theme color value: one CSS color applied to both schemes, or separate
|
|
191
|
+
* values per scheme. Tokens left unset fall back to the built-in defaults of
|
|
192
|
+
* each scheme, so overriding a light color never degrades dark mode.
|
|
193
|
+
*/
|
|
194
|
+
type AgentThemeColor = string | {
|
|
195
|
+
dark?: string;
|
|
196
|
+
light?: string;
|
|
197
|
+
};
|
|
198
|
+
/** Corner rounding preset applied across the embed surface and fields. */
|
|
199
|
+
type AgentRadius = "pill" | "round" | "sharp" | "soft";
|
|
200
|
+
/**
|
|
201
|
+
* The seven high-impact color tokens. Everything else in the embed
|
|
202
|
+
* (borders, shadows, chart palettes) derives from these and from the
|
|
203
|
+
* built-in scheme defaults.
|
|
204
|
+
*/
|
|
205
|
+
type AgentThemeColors = {
|
|
206
|
+
/** Primary action and highlight color. Chart palettes derive from it. */
|
|
207
|
+
accent?: AgentThemeColor;
|
|
208
|
+
/** Chat panel background. */
|
|
209
|
+
background?: AgentThemeColor;
|
|
210
|
+
/** Primary text color. */
|
|
211
|
+
foreground?: AgentThemeColor;
|
|
212
|
+
/** Dropdown and popover surface color. */
|
|
213
|
+
overlay?: AgentThemeColor;
|
|
214
|
+
/** Card surface color. */
|
|
215
|
+
surface?: AgentThemeColor;
|
|
216
|
+
/** Secondary surface color (chips, muted fills). */
|
|
217
|
+
surfaceSecondary?: AgentThemeColor;
|
|
218
|
+
/** Tooltip surface color. Text contrast is derived automatically. */
|
|
219
|
+
tooltip?: AgentThemeColor;
|
|
220
|
+
};
|
|
221
|
+
type AgentTypography = {
|
|
222
|
+
/**
|
|
223
|
+
* Base font size in pixels (clamped to 12–18).
|
|
224
|
+
* @default 14
|
|
225
|
+
*/
|
|
226
|
+
baseSize?: number;
|
|
227
|
+
/** CSS font family stack, e.g. `"Geist, sans-serif"`. */
|
|
228
|
+
fontFamily?: string;
|
|
229
|
+
};
|
|
230
|
+
/**
|
|
231
|
+
* HeroUI Pro theme variant applied to the agent surface.
|
|
232
|
+
*
|
|
233
|
+
* Anything other than `"base"` also needs its stylesheet loaded once, from the
|
|
234
|
+
* licensed Pro package: `import "@heroui-pro/react/agent-themes/glass"`.
|
|
235
|
+
*/
|
|
236
|
+
type AgentDesignTheme = "base" | "brutalism" | "glass" | "mouve";
|
|
237
|
+
declare const AGENT_DESIGN_THEMES: readonly AgentDesignTheme[];
|
|
238
|
+
/**
|
|
239
|
+
* Intentionally small theme surface: one color scheme, one Pro variant, four
|
|
240
|
+
* radius presets, seven color tokens, and basic typography. No named themes,
|
|
241
|
+
* extend chains, or per-component tokens.
|
|
242
|
+
*/
|
|
243
|
+
type AgentThemeOptions = {
|
|
244
|
+
/** @default "system" */
|
|
245
|
+
colorScheme?: AgentColorScheme;
|
|
246
|
+
colors?: AgentThemeColors;
|
|
247
|
+
/**
|
|
248
|
+
* HeroUI Pro theme variant. Requires the matching stylesheet import.
|
|
249
|
+
* @default "base"
|
|
250
|
+
*/
|
|
251
|
+
designTheme?: AgentDesignTheme;
|
|
252
|
+
/** @default "round" */
|
|
253
|
+
radius?: AgentRadius;
|
|
254
|
+
typography?: AgentTypography;
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
type AgentComponentExportFormat = "csv" | "png" | "svg";
|
|
258
|
+
type AgentPermissionMode = AgentPermissionMode$1;
|
|
259
|
+
/** MIME type accepted by the hosted HeroUI Agent attachment pipeline. */
|
|
260
|
+
type AgentAttachmentContentType = HeroUIAgentAttachmentContentType;
|
|
261
|
+
type AgentMessageAction = MessageActionKind;
|
|
262
|
+
type AgentFeedbackReason = MessageFeedbackReason;
|
|
263
|
+
type AgentResponseFeedback = {
|
|
264
|
+
/** Optional free-form context supplied by the end user. */
|
|
265
|
+
comment?: string;
|
|
266
|
+
conversationId: string;
|
|
267
|
+
messageId: string;
|
|
268
|
+
rating: "negative" | "positive";
|
|
269
|
+
/** Structured reasons selected for negative feedback. Empty for positive feedback. */
|
|
270
|
+
reasons: AgentFeedbackReason[];
|
|
271
|
+
};
|
|
272
|
+
type AgentContext = Record<string, unknown>;
|
|
273
|
+
/**
|
|
274
|
+
* The single shared context object. It is passed as the second argument to
|
|
275
|
+
* every client tool's `execute` — API clients, user info, state setters.
|
|
276
|
+
* Anything goes; it never leaves the browser.
|
|
277
|
+
*
|
|
278
|
+
* One key is reserved: `page`. When present, the SDK calls it on every turn
|
|
279
|
+
* and sends its JSON-serializable return value (route, filters, selection —
|
|
280
|
+
* max 16KB) to the agent as page context. Nothing else in the context object
|
|
281
|
+
* ever crosses the wire.
|
|
282
|
+
*/
|
|
283
|
+
type AgentSharedContext = {
|
|
284
|
+
page?: () => AgentContext | Promise<AgentContext>;
|
|
285
|
+
} & Record<string, unknown>;
|
|
286
|
+
type AgentViewMode = "floating" | "sidebar";
|
|
287
|
+
type AgentMarkdownAnimation = boolean | AnimateOptions;
|
|
288
|
+
type AgentMarkdownCaret = "block" | "circle";
|
|
289
|
+
type AgentMarkdownRenderer = CustomRenderer;
|
|
290
|
+
type AgentMarkdownRendererProps = CustomRendererProps;
|
|
291
|
+
type AgentMarkdownPlugins = {
|
|
292
|
+
/** Custom renderers selected by fenced-code language. */
|
|
293
|
+
renderers?: AgentMarkdownRenderer[];
|
|
294
|
+
};
|
|
295
|
+
/** Streaming Markdown presentation and custom fenced-code renderers. */
|
|
296
|
+
type AgentMarkdownOptions = {
|
|
297
|
+
/**
|
|
298
|
+
* Animate newly streamed content. Pass `false` to disable text animation.
|
|
299
|
+
* @default {animation: "blurIn", duration: 160, easing: "ease-out", sep: "word", stagger: 18}
|
|
300
|
+
*/
|
|
301
|
+
animated?: AgentMarkdownAnimation;
|
|
302
|
+
/** Streaming caret style. Pass `false` to hide it. @default "block" */
|
|
303
|
+
caret?: AgentMarkdownCaret | false;
|
|
304
|
+
/** Custom fenced-code renderers. */
|
|
305
|
+
plugins?: AgentMarkdownPlugins;
|
|
306
|
+
};
|
|
307
|
+
/** Corner that anchors the launcher button and the floating panel. */
|
|
308
|
+
type AgentLauncherPosition = "bottom-left" | "bottom-right";
|
|
309
|
+
/** Placement of the floating launcher button (visibility is `showLauncher`). */
|
|
310
|
+
type AgentLauncherOptions = {
|
|
311
|
+
/**
|
|
312
|
+
* Fill of the launcher button. Defaults to the accent color; set it when a
|
|
313
|
+
* custom {@link icon} needs a different backdrop. The mark inside gets a
|
|
314
|
+
* contrasting foreground automatically.
|
|
315
|
+
*/
|
|
316
|
+
background?: AgentThemeColor;
|
|
317
|
+
/**
|
|
318
|
+
* Image rendered inside the launcher button instead of the built-in spark
|
|
319
|
+
* mark. Use a square asset (70x70 or larger); it is scaled to fit.
|
|
320
|
+
*/
|
|
321
|
+
icon?: string;
|
|
322
|
+
/**
|
|
323
|
+
* Pixel offsets from the anchored corner: `x` from the side edge, `y` from
|
|
324
|
+
* the bottom. Defaults to 24 (16 on small screens).
|
|
325
|
+
*/
|
|
326
|
+
offset?: {
|
|
327
|
+
x?: number;
|
|
328
|
+
y?: number;
|
|
329
|
+
};
|
|
330
|
+
/** @default "bottom-right" */
|
|
331
|
+
position?: AgentLauncherPosition;
|
|
332
|
+
/**
|
|
333
|
+
* Escape hatch for launcher styling the options above do not cover, applied
|
|
334
|
+
* as inline styles on the button (so it wins over the stylesheet). Prefer the
|
|
335
|
+
* dedicated options where they exist; this is not covered by the embed's
|
|
336
|
+
* visual defaults and can break the button's layout.
|
|
337
|
+
*/
|
|
338
|
+
style?: CSSProperties;
|
|
339
|
+
};
|
|
340
|
+
/** Optional hosted-agent capabilities, all off by default. */
|
|
341
|
+
type AgentCapabilities = {
|
|
342
|
+
/**
|
|
343
|
+
* Allow the hosted agent to search for images via web search. Only applies
|
|
344
|
+
* when {@link webSearch} is enabled; defaults to true in that case.
|
|
345
|
+
* @default true
|
|
346
|
+
*/
|
|
347
|
+
imageSearch?: boolean;
|
|
348
|
+
/**
|
|
349
|
+
* Allow the hosted agent to search the public web for current information
|
|
350
|
+
* and images. Results are untrusted external content; keep this off when the
|
|
351
|
+
* assistant should only ever answer from your declared client tools.
|
|
352
|
+
* @default false
|
|
353
|
+
*/
|
|
354
|
+
webSearch?: boolean;
|
|
355
|
+
};
|
|
356
|
+
/** Browser client-tool approval policy. */
|
|
357
|
+
type AgentPermissionOptions = {
|
|
358
|
+
/**
|
|
359
|
+
* Permission mode used before an end user chooses another mode.
|
|
360
|
+
* `"ask"` gates every client tool, `"auto"` gates only tools marked
|
|
361
|
+
* `needsApproval`, and `"full"` runs client tools without prompting.
|
|
362
|
+
* @default "auto"
|
|
363
|
+
*/
|
|
364
|
+
defaultMode?: AgentPermissionMode;
|
|
365
|
+
/**
|
|
366
|
+
* Show the permission picker in the composer, letting the end user switch
|
|
367
|
+
* modes for themselves.
|
|
368
|
+
*
|
|
369
|
+
* This is a privilege boundary, not just a control: it permits the end user
|
|
370
|
+
* to select `"full"` and run every client tool without approval, overriding
|
|
371
|
+
* {@link defaultMode}. Their choice persists for the conversation.
|
|
372
|
+
*
|
|
373
|
+
* The picker only renders when {@link HeroUIAgentProps.tools} is non-empty,
|
|
374
|
+
* since there is nothing to approve otherwise.
|
|
375
|
+
* @default false
|
|
376
|
+
*/
|
|
377
|
+
showPicker?: boolean;
|
|
378
|
+
};
|
|
379
|
+
/**
|
|
380
|
+
* Size and expansion of the chat panel. In `floating` mode expansion grows the
|
|
381
|
+
* card; in `sidebar` mode it temporarily fills the viewport. Initial dimensions
|
|
382
|
+
* are ignored in `sidebar` mode and below the mobile breakpoint.
|
|
383
|
+
*/
|
|
384
|
+
type AgentPanelOptions = {
|
|
385
|
+
/**
|
|
386
|
+
* Open the panel expanded. End users can still collapse it unless
|
|
387
|
+
* {@link expandable} is off.
|
|
388
|
+
* @default false
|
|
389
|
+
*/
|
|
390
|
+
expanded?: boolean;
|
|
391
|
+
/**
|
|
392
|
+
* Offer the expand control in the panel header. In sidebar mode the expanded
|
|
393
|
+
* panel fills the viewport. Turn it off to pin the panel to one size.
|
|
394
|
+
* @default true
|
|
395
|
+
*/
|
|
396
|
+
expandable?: boolean;
|
|
397
|
+
/**
|
|
398
|
+
* Panel height before expanding — a number in pixels or any CSS length.
|
|
399
|
+
* Capped to the viewport.
|
|
400
|
+
* @default "max(420px, 56dvh)"
|
|
401
|
+
*/
|
|
402
|
+
initialHeight?: number | string;
|
|
403
|
+
/**
|
|
404
|
+
* Panel width before expanding — a number in pixels or any CSS length.
|
|
405
|
+
* Expanding widens the panel from here. Capped to the viewport.
|
|
406
|
+
* @default 440
|
|
407
|
+
*/
|
|
408
|
+
initialWidth?: number | string;
|
|
409
|
+
};
|
|
410
|
+
/** Visual presentation: view mode, theme, panel size, and launcher placement. */
|
|
411
|
+
type AgentAppearance = {
|
|
412
|
+
/** Where the launcher button (and the floating panel) is anchored. */
|
|
413
|
+
launcher?: AgentLauncherOptions;
|
|
414
|
+
/** Size and expansion of the floating panel. */
|
|
415
|
+
panel?: AgentPanelOptions;
|
|
416
|
+
theme?: AgentThemeOptions;
|
|
417
|
+
/**
|
|
418
|
+
* How the chat opens: `"floating"` (default) is a floating rounded panel in
|
|
419
|
+
* the corner; `"sidebar"` docks full-height to the right edge of the page.
|
|
420
|
+
*/
|
|
421
|
+
viewMode?: AgentViewMode;
|
|
422
|
+
};
|
|
423
|
+
/** Message composer settings. */
|
|
424
|
+
type AgentComposerOptions = {
|
|
425
|
+
/**
|
|
426
|
+
* File types end users can attach. Omit to allow every supported type, pass
|
|
427
|
+
* a subset to narrow the picker, or pass `false` to remove attachments.
|
|
428
|
+
* @default all supported attachment types
|
|
429
|
+
*/
|
|
430
|
+
attachments?: AgentAttachmentContentType[] | false;
|
|
431
|
+
/**
|
|
432
|
+
* Model used for new turns before an end user chooses another model.
|
|
433
|
+
* When the picker is disabled, this pins every turn to the configured model.
|
|
434
|
+
*/
|
|
435
|
+
defaultModel?: AgentModelId;
|
|
436
|
+
/** Show microphone recording and voice transcription controls. @default true */
|
|
437
|
+
dictation?: boolean;
|
|
438
|
+
/**
|
|
439
|
+
* Small verification notice shown below the composer and above the HeroUI
|
|
440
|
+
* attribution. Supports `[label](example.com)` and HTTPS links; bare domains
|
|
441
|
+
* are normalized to HTTPS. Limited to 240 characters. Pass `false` or omit it
|
|
442
|
+
* to hide the notice.
|
|
443
|
+
* @default false
|
|
444
|
+
* @example "Agent may make mistakes. [View terms](https://example.com/terms)"
|
|
445
|
+
*/
|
|
446
|
+
disclaimer?: string | false;
|
|
447
|
+
/** Let the end user choose from the hosted agent's allowlisted models. @default false */
|
|
448
|
+
modelPicker?: boolean;
|
|
449
|
+
/** Placeholder shown in the message composer. @default "Ask anything…" */
|
|
450
|
+
placeholder?: string;
|
|
451
|
+
};
|
|
452
|
+
/** The empty-conversation view shown before the first message. */
|
|
453
|
+
type AgentStartScreenOptions = {
|
|
454
|
+
/** Heading shown above the composer. @default "Ask about your data" */
|
|
455
|
+
greeting?: string;
|
|
456
|
+
/** Show and enable `Ctrl+1`…`Ctrl+5` shortcuts for the visible prompts. @default false */
|
|
457
|
+
promptShortcuts?: boolean;
|
|
458
|
+
/** Up to five suggested prompts (each max 160 characters). */
|
|
459
|
+
prompts?: string[];
|
|
460
|
+
};
|
|
461
|
+
/** Internal — for HeroUI platform development only. */
|
|
462
|
+
type AgentApiOverrides = {
|
|
463
|
+
baseUrl?: string;
|
|
464
|
+
realtimeUrl?: string;
|
|
465
|
+
};
|
|
466
|
+
/**
|
|
467
|
+
* Short-lived browser credential returned by the customer's server.
|
|
468
|
+
*
|
|
469
|
+
* Declared here rather than re-exported from `@heroui/agent-client`: that
|
|
470
|
+
* package is bundled into this one, so a re-export would leave a dangling
|
|
471
|
+
* reference in the published typings. The two declarations are structurally
|
|
472
|
+
* identical, which is what lets the session manager accept this callback.
|
|
473
|
+
*/
|
|
474
|
+
type AgentAuthToken = {
|
|
475
|
+
expiresAt: number;
|
|
476
|
+
token: string;
|
|
477
|
+
};
|
|
478
|
+
/** Context supplied whenever the SDK needs a fresh browser credential. */
|
|
479
|
+
type GetAuthTokenContext = {
|
|
480
|
+
anonymousId: string;
|
|
481
|
+
agentId: string;
|
|
482
|
+
};
|
|
483
|
+
type GetAuthToken = (context: GetAuthTokenContext) => Promise<AgentAuthToken>;
|
|
484
|
+
type HeroUIAgentProps = {
|
|
485
|
+
/** Internal — for HeroUI platform development only. */
|
|
486
|
+
_api?: AgentApiOverrides;
|
|
487
|
+
appearance?: AgentAppearance;
|
|
488
|
+
capabilities?: AgentCapabilities;
|
|
489
|
+
/** Component export formats to show. Pass `false` to hide export and copy controls. */
|
|
490
|
+
componentExports?: AgentComponentExportFormat[] | false;
|
|
491
|
+
composer?: AgentComposerOptions;
|
|
492
|
+
/**
|
|
493
|
+
* Shared context for client tools; its reserved `page` key supplies the
|
|
494
|
+
* page context sent to the agent. See {@link AgentSharedContext}.
|
|
495
|
+
*/
|
|
496
|
+
context?: AgentSharedContext;
|
|
497
|
+
/**
|
|
498
|
+
* Fetches a short-lived browser credential from the host application's
|
|
499
|
+
* server. Never expose a HeroUI Agent API key in browser code.
|
|
500
|
+
*/
|
|
501
|
+
getAuthToken: GetAuthToken;
|
|
502
|
+
/** Streaming Markdown animation, caret, and custom fenced-code renderers. */
|
|
503
|
+
markdown?: AgentMarkdownOptions;
|
|
504
|
+
/**
|
|
505
|
+
* Receives end-user ratings for assistant responses. Negative ratings can
|
|
506
|
+
* include structured reasons and an optional comment from the feedback popover.
|
|
507
|
+
*/
|
|
508
|
+
onFeedback?: (feedback: AgentResponseFeedback) => Promise<void> | void;
|
|
509
|
+
/** Client-tool approval defaults and optional end-user picker. */
|
|
510
|
+
permissions?: AgentPermissionOptions;
|
|
511
|
+
/**
|
|
512
|
+
* Warm the agent up before the visitor touches it: fetch the chat engine,
|
|
513
|
+
* bootstrap the conversation, and boot the agent run — all while the panel is
|
|
514
|
+
* still closed, at the browser's idle priority so it never competes with your
|
|
515
|
+
* page's own loading. The first open is then immediate instead of showing a
|
|
516
|
+
* loading state.
|
|
517
|
+
*
|
|
518
|
+
* Set to `false` to request nothing until the panel is opened. Worth doing
|
|
519
|
+
* when most visitors never open the agent, or on pages where you want to
|
|
520
|
+
* choose the moment yourself — `useAgent().preload()` runs the same warm-up
|
|
521
|
+
* on your signal.
|
|
522
|
+
* @default true
|
|
523
|
+
*/
|
|
524
|
+
preload?: boolean;
|
|
525
|
+
agentId: string;
|
|
526
|
+
/**
|
|
527
|
+
* Apply the appearance saved for this project in the HeroUI dashboard —
|
|
528
|
+
* launcher icon, colors, typography, greeting, and suggested prompts —
|
|
529
|
+
* without redeploying.
|
|
530
|
+
*
|
|
531
|
+
* Anything passed in code wins, field by field, so this only fills in what
|
|
532
|
+
* you left unset. Pass `false` to ignore the dashboard entirely and
|
|
533
|
+
* configure the embed exclusively from props.
|
|
534
|
+
* @default true
|
|
535
|
+
*/
|
|
536
|
+
remoteConfig?: boolean;
|
|
537
|
+
/**
|
|
538
|
+
* Per-message actions shown under assistant responses: `"copy"` copies the
|
|
539
|
+
* response text, `"feedback"` shows thumbs up/down, `"retry"` regenerates
|
|
540
|
+
* the last response. Pass `false` to hide all actions.
|
|
541
|
+
* @default ["copy", "feedback", "retry"]
|
|
542
|
+
*/
|
|
543
|
+
responseActions?: AgentMessageAction[] | false;
|
|
544
|
+
/**
|
|
545
|
+
* Show the floating launcher button when the panel is closed. Set to
|
|
546
|
+
* `false` when opening the agent exclusively through `useAgent()`.
|
|
547
|
+
* @default true
|
|
548
|
+
*/
|
|
549
|
+
showLauncher?: boolean;
|
|
550
|
+
startScreen?: AgentStartScreenOptions;
|
|
551
|
+
/**
|
|
552
|
+
* Client tools the agent can call in the user's browser. Define with
|
|
553
|
+
* `createToolHelper<Context>()` for typed args and context.
|
|
554
|
+
*/
|
|
555
|
+
tools?: ClientTool[];
|
|
556
|
+
};
|
|
557
|
+
type AgentController = {
|
|
558
|
+
hide: () => void;
|
|
559
|
+
newConversation: () => void;
|
|
560
|
+
/**
|
|
561
|
+
* Warm the agent now, without opening it — the same work the `preload` prop
|
|
562
|
+
* does on its own. Pair it with `preload={false}` to pick the moment from
|
|
563
|
+
* your own signal: a pricing page, a scroll depth, a form the visitor is
|
|
564
|
+
* struggling with. Cheap to call repeatedly; the work happens once.
|
|
565
|
+
*/
|
|
566
|
+
preload: () => void;
|
|
567
|
+
refreshAuth: () => void;
|
|
568
|
+
show: () => void;
|
|
569
|
+
shutdown: () => void;
|
|
570
|
+
toggle: () => void;
|
|
571
|
+
};
|
|
572
|
+
|
|
573
|
+
/**
|
|
574
|
+
* Imperative controls for the embedded agent. Safe to call before
|
|
575
|
+
* `<HeroUIAgent />` mounts (calls are ignored with a console warning). Pass a
|
|
576
|
+
* `agentId` when rendering more than one agent on the same page.
|
|
577
|
+
*/
|
|
578
|
+
declare function useAgent(agentId?: string): AgentController;
|
|
579
|
+
/**
|
|
580
|
+
* One-line agent embed:
|
|
581
|
+
*
|
|
582
|
+
* ```tsx
|
|
583
|
+
* <body>
|
|
584
|
+
* {children}
|
|
585
|
+
* <HeroUIAgent getAuthToken={getAuthToken} agentId="proj_..." />
|
|
586
|
+
* </body>
|
|
587
|
+
* ```
|
|
588
|
+
*
|
|
589
|
+
* Renders nothing in the tree; the launcher and chat panel mount into an
|
|
590
|
+
* independent React root on `document.body`.
|
|
591
|
+
*/
|
|
592
|
+
declare function HeroUIAgent(props: HeroUIAgentProps): null;
|
|
593
|
+
|
|
594
|
+
export { AGENT_DESIGN_THEMES, AGENT_MODEL_IDS, AGENT_MODEL_OPTIONS, type AgentApiOverrides, type AgentAppearance, type AgentAttachmentContentType, type AgentAuthToken, type AgentCapabilities, type AgentColorScheme, type AgentComponentExportFormat, type AgentComposerOptions, type AgentContext, type AgentController, type AgentDesignTheme, type AgentFeedbackReason, type AgentLauncherOptions, type AgentLauncherPosition, type AgentMarkdownAnimation, type AgentMarkdownCaret, type AgentMarkdownOptions, type AgentMarkdownPlugins, type AgentMarkdownRenderer, type AgentMarkdownRendererProps, type AgentMessageAction, type AgentModelId, type AgentModelOption, type AgentModelTier, type AgentPanelOptions, type AgentPermissionMode, type AgentPermissionOptions, type AgentRadius, type AgentResponseFeedback, type AgentSharedContext, type AgentStartScreenOptions, type AgentThemeColor, type AgentThemeColors, type AgentThemeOptions, type AgentTypography, type AgentViewMode, type ClientTool, type ClientToolIconProps, type ClientToolRenderProps, type ClientToolStatus, DEFAULT_AGENT_PICKER_MODEL_ID, type GetAuthToken, type GetAuthTokenContext, HeroUIAgent, type HeroUIAgentProps, LEGACY_AGENT_MODEL_IDS, createToolHelper, getAgentModelTier, isAgentModelId, resolveAgentModelId, useAgent };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import {
|
|
2
|
+
HeroUIAgent,
|
|
3
|
+
useAgent
|
|
4
|
+
} from "./chunk-GDDNN2XY.js";
|
|
5
|
+
import {
|
|
6
|
+
AGENT_DESIGN_THEMES,
|
|
7
|
+
AGENT_MODEL_IDS,
|
|
8
|
+
AGENT_MODEL_OPTIONS,
|
|
9
|
+
DEFAULT_AGENT_PICKER_MODEL_ID,
|
|
10
|
+
LEGACY_AGENT_MODEL_IDS,
|
|
11
|
+
createToolHelper,
|
|
12
|
+
getAgentModelTier,
|
|
13
|
+
isAgentModelId,
|
|
14
|
+
resolveAgentModelId
|
|
15
|
+
} from "./chunk-RQCTC4JB.js";
|
|
16
|
+
export {
|
|
17
|
+
AGENT_DESIGN_THEMES,
|
|
18
|
+
AGENT_MODEL_IDS,
|
|
19
|
+
AGENT_MODEL_OPTIONS,
|
|
20
|
+
DEFAULT_AGENT_PICKER_MODEL_ID,
|
|
21
|
+
HeroUIAgent,
|
|
22
|
+
LEGACY_AGENT_MODEL_IDS,
|
|
23
|
+
createToolHelper,
|
|
24
|
+
getAgentModelTier,
|
|
25
|
+
isAgentModelId,
|
|
26
|
+
resolveAgentModelId,
|
|
27
|
+
useAgent
|
|
28
|
+
};
|