@heroui/agent 1.0.0-beta.1 → 1.0.0-beta.11

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 (53) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +195 -72
  3. package/dist/chunk-AMNE7O54.js +1 -0
  4. package/dist/chunk-AR424OVX.js +1 -0
  5. package/dist/chunk-FZXNXBTZ.js +1 -0
  6. package/dist/chunk-IGSNBYO2.js +1 -0
  7. package/dist/chunk-KFWXAD55.js +1 -0
  8. package/dist/chunk-QSLALU5G.js +1 -0
  9. package/dist/client-tools-manifest-PCUOVUXR.js +1 -0
  10. package/dist/css/index.css +1 -2
  11. package/dist/index.d.ts +9 -669
  12. package/dist/index.js +1 -1
  13. package/dist/internal/host.d.ts +188 -0
  14. package/dist/internal/host.js +1 -0
  15. package/dist/internal/shared.d.ts +67 -0
  16. package/dist/internal/shared.js +1 -0
  17. package/dist/next.d.ts +3 -4
  18. package/dist/next.js +1 -1
  19. package/dist/persistence-YI6JSYCT.js +1 -0
  20. package/dist/server.d.ts +23 -2
  21. package/dist/server.js +1 -1
  22. package/dist/types-C3g7R0hr.d.ts +592 -0
  23. package/dist/version-BNdyk3rt.d.ts +5 -0
  24. package/dist/zod.d.ts +1 -0
  25. package/dist/zod.js +5 -0
  26. package/package.json +25 -37
  27. package/dist/chart-content-BBHQVMP4.js +0 -1
  28. package/dist/chunk-4JEZZR5J.js +0 -1
  29. package/dist/chunk-5RHO3S5E.js +0 -2
  30. package/dist/chunk-64RI74L5.js +0 -1
  31. package/dist/chunk-6ZJJN322.js +0 -1
  32. package/dist/chunk-7KCGPNEN.js +0 -1
  33. package/dist/chunk-BBB5EHDN.js +0 -5
  34. package/dist/chunk-CLHBM3HQ.js +0 -1
  35. package/dist/chunk-CR3H7AVI.js +0 -1
  36. package/dist/chunk-HCLXS4HQ.js +0 -1
  37. package/dist/chunk-PZJ4NC3J.js +0 -1
  38. package/dist/chunk-RNNGE7KM.js +0 -1
  39. package/dist/chunk-S6OIAJSC.js +0 -1
  40. package/dist/chunk-UHHKMESI.js +0 -1
  41. package/dist/chunk-USFF5UMB.js +0 -2
  42. package/dist/component-renderer-XOCP6UFF.js +0 -1
  43. package/dist/composer-draft-NSKK65F3.js +0 -1
  44. package/dist/composer-image-draft-KAGTNQR7.js +0 -1
  45. package/dist/contracts.d.ts +0 -1651
  46. package/dist/contracts.js +0 -2
  47. package/dist/embed-runtime-FP77ORXA.js +0 -5
  48. package/dist/identity-3P8-17km.d.ts +0 -95
  49. package/dist/interactive-map-surface-WC2LPCR7.js +0 -1
  50. package/dist/internal/client-tools.js +0 -1
  51. package/dist/internal/models.js +0 -1
  52. package/dist/internal/runtime.js +0 -1
  53. package/dist/internal/theme.js +0 -1
@@ -0,0 +1,592 @@
1
+ import { CSSProperties } from 'react';
2
+
3
+ /**
4
+ * Deliberately Zod-free: `createToolHelper` and these types are re-exported from
5
+ * the package root, which the panel shell is served from. The manifest
6
+ * serializer that does need Zod lives in `./client-tools-manifest`.
7
+ */
8
+ type ClientToolStatus = "input-streaming" | "approval-requested" | "executing" | "completed" | "rejected" | "error";
9
+ /** HeroUI-owned icon rendered by the hosted Agent tool card. */
10
+ type ClientToolIcon = "add" | "database" | "delete" | "edit" | "navigate" | "search" | "sparkles" | "view";
11
+ type ClientToolSchema<TArgs> = {
12
+ parse: (input: unknown) => TArgs;
13
+ safeParse: (input: unknown) => unknown;
14
+ };
15
+ type AgentDataSourceFormat = "csv" | "json" | "tsv";
16
+ /** An inline image from any client tool, delivered to the model with its JSON details. */
17
+ type ClientToolVisualResult = Record<string, unknown> & {
18
+ kind: "heroui-agent-visual-result";
19
+ image: {
20
+ /** Base64 without a data-URL prefix; at most 40,000 characters. */
21
+ data: string;
22
+ mediaType: "image/jpeg" | "image/png";
23
+ };
24
+ };
25
+ /** A private, conversation-scoped dataset uploaded by a browser client tool. */
26
+ type AgentDataSource = Readonly<{
27
+ filename: string;
28
+ format: AgentDataSourceFormat;
29
+ id: string;
30
+ kind: "heroui-agent-data-source";
31
+ mediaType: "application/json" | "text/csv" | "text/tab-separated-values";
32
+ size: number;
33
+ url: string;
34
+ }>;
35
+ type UploadAgentDataSourceInput = Readonly<{
36
+ /** JSON value, delimited text, Blob, ArrayBuffer, or byte array. */
37
+ data: unknown;
38
+ filename?: string;
39
+ format?: AgentDataSourceFormat;
40
+ }>;
41
+ /**
42
+ * Stable identity for one agent-initiated browser tool effect. Pass
43
+ * `idempotencyKey` through to mutation APIs so an ambiguous network retry can
44
+ * return the original result instead of applying the side effect twice.
45
+ */
46
+ type ClientToolExecutionContext = Readonly<{
47
+ signal: AbortSignal;
48
+ conversationId: string;
49
+ idempotencyKey: string;
50
+ toolCallId: string;
51
+ /** Upload a large result without placing its bytes in the 64 KiB tool receipt. */
52
+ uploadDataSource: (input: UploadAgentDataSourceInput) => Promise<AgentDataSource>;
53
+ }>;
54
+ /**
55
+ * A tool the agent can call in the user's browser. Execution stays in the
56
+ * customer page; the hosted iframe receives only its declarative manifest and
57
+ * a validated result.
58
+ */
59
+ type ClientTool<TArgs = any, TContext = any> = {
60
+ description: string;
61
+ /** Human-readable name shown in the default tool card. Defaults to `name`. */
62
+ displayName?: string;
63
+ execute: (args: TArgs, context: TContext, execution: ClientToolExecutionContext) => Promise<unknown> | unknown;
64
+ /** HeroUI-owned icon rendered by the hosted tool card. */
65
+ icon?: ClientToolIcon;
66
+ iconColor?: string;
67
+ name: string;
68
+ /** When true, the user must approve the call before `execute` runs. */
69
+ needsApproval?: boolean;
70
+ /** Zod schema (typed) or raw JSON Schema object for the tool parameters. */
71
+ parameters: ClientToolSchema<TArgs> | Record<string, unknown>;
72
+ };
73
+ /**
74
+ * Returns a type-safe tool factory bound to your shared context type:
75
+ *
76
+ * ```ts
77
+ * type AppContext = {apiClient: ApiClient};
78
+ * const tool = createToolHelper<AppContext>();
79
+ * const tools = [tool({name: "search_users", parameters: z.object({...}), execute: (args, ctx) => ...})];
80
+ * ```
81
+ */
82
+ declare function createToolHelper<TContext>(): <TArgs>(definition: ClientTool<TArgs, TContext>) => ClientTool<TArgs, TContext>;
83
+ /** Parses model-provided args with the local Zod schema when available. */
84
+ declare function parseClientToolArgs(tool: ClientTool, input: unknown): unknown;
85
+ /**
86
+ * Resolves a component "tool" action (a rendered button's toolCall) to the
87
+ * client tool it may execute directly in the page. Unknown and approval-gated
88
+ * tools return null — those actions fall back to their composer prompt so
89
+ * nothing ever runs without the user seeing it first.
90
+ */
91
+ declare function resolveDirectToolAction(tools: ReadonlyMap<string, ClientTool>, toolName: string): ClientTool | null;
92
+
93
+ /**
94
+ * Light/dark color scheme selection for the embed. `"system"` follows the
95
+ * OS preference and updates live when it changes.
96
+ */
97
+ type AgentColorScheme = "dark" | "light" | "system";
98
+ /**
99
+ * A theme color value: one CSS color applied to both schemes, or separate
100
+ * values per scheme. Tokens left unset fall back to the built-in defaults of
101
+ * each scheme, so overriding a light color never degrades dark mode.
102
+ */
103
+ type AgentThemeColor = string | {
104
+ dark?: string;
105
+ light?: string;
106
+ };
107
+ /** Corner rounding preset applied across the embed surface and fields. */
108
+ type AgentRadius = "pill" | "round" | "sharp" | "soft";
109
+ /**
110
+ * The seven high-impact color tokens. Everything else in the embed
111
+ * (borders, shadows, chart palettes) derives from these and from the
112
+ * built-in scheme defaults.
113
+ */
114
+ type AgentThemeColors = {
115
+ /** Primary action and highlight color. Chart palettes derive from it. */
116
+ accent?: AgentThemeColor;
117
+ /** Chat panel background. */
118
+ background?: AgentThemeColor;
119
+ /** Primary text color. */
120
+ foreground?: AgentThemeColor;
121
+ /** Dropdown and popover surface color. */
122
+ overlay?: AgentThemeColor;
123
+ /** Card surface color. */
124
+ surface?: AgentThemeColor;
125
+ /** Secondary surface color (chips, muted fills). */
126
+ surfaceSecondary?: AgentThemeColor;
127
+ /** Tooltip surface color. Text contrast is derived automatically. */
128
+ tooltip?: AgentThemeColor;
129
+ };
130
+ type AgentTypography = {
131
+ /**
132
+ * Base font size in pixels (clamped to 12–18).
133
+ * @default 14
134
+ */
135
+ baseSize?: number;
136
+ /** CSS font family stack, e.g. `"Geist, sans-serif"`. */
137
+ fontFamily?: string;
138
+ };
139
+ /**
140
+ * HeroUI Pro theme variant applied to the agent surface, e.g. `"base"`,
141
+ * `"brutalism"`, `"glass"`, or `"mouve"`.
142
+ *
143
+ * Hosted Agent deployments own the list of supported variants and activate the
144
+ * selected one inside the iframe; unknown values fall back to `"base"`, so new
145
+ * variants never require an SDK update.
146
+ */
147
+ type AgentDesignTheme = string;
148
+ /**
149
+ * Intentionally small theme surface: one color scheme, one Pro variant, four
150
+ * radius presets, seven color tokens, and basic typography. No named themes,
151
+ * extend chains, or per-component tokens.
152
+ */
153
+ type AgentThemeOptions = {
154
+ /** @default "system" */
155
+ colorScheme?: AgentColorScheme;
156
+ colors?: AgentThemeColors;
157
+ /**
158
+ * HeroUI Pro theme variant rendered by the hosted Agent.
159
+ * @default "base"
160
+ */
161
+ designTheme?: AgentDesignTheme;
162
+ /** @default "round" */
163
+ radius?: AgentRadius;
164
+ typography?: AgentTypography;
165
+ };
166
+
167
+ type AgentComponentExportFormat = "csv" | "png" | "svg";
168
+ type AgentPermissionMode = "ask" | "auto" | "full";
169
+ /**
170
+ * MIME type accepted by the hosted HeroUI Agent attachment pipeline, e.g.
171
+ * `"application/pdf"` or `"text/csv"`. The hosted Agent owns the supported
172
+ * list and ignores unknown types, so new formats never require an SDK update.
173
+ * See https://heroui.pro/docs/agents/api-reference/configuration.
174
+ */
175
+ type AgentAttachmentContentType = string;
176
+ /**
177
+ * Model id from the hosted HeroUI Agent catalog, e.g. `"google/gemini-3.8-flash"`.
178
+ * The hosted Agent owns the catalog: retired ids resolve to their replacement
179
+ * and unknown ids fall back to the default model, so new models never require
180
+ * an SDK update. See https://heroui.pro/docs/agents/api-reference/models.
181
+ */
182
+ type AgentModelId = string;
183
+ type AgentMessageAction = "copy" | "feedback" | "retry";
184
+ type AgentFeedbackReason = "did_not_follow_instructions" | "incomplete" | "incorrect" | "not_relevant" | "other" | "unclear";
185
+ type AgentResponseFeedback = {
186
+ /** Optional free-form context supplied by the end user. */
187
+ comment?: string;
188
+ conversationId: string;
189
+ messageId: string;
190
+ rating: "negative" | "positive";
191
+ /** Structured reasons selected for negative feedback. Empty for positive feedback. */
192
+ reasons: AgentFeedbackReason[];
193
+ };
194
+ type AgentContext = Record<string, unknown>;
195
+ /**
196
+ * The single shared context object. It is passed as the second argument to
197
+ * every client tool's `execute` — API clients, user info, state setters.
198
+ * Anything goes; it never leaves the browser.
199
+ *
200
+ * One key is reserved: `page`. When present, the SDK calls it on every turn
201
+ * and sends its JSON-serializable return value (route, filters, selection —
202
+ * max 16KB) to the agent as page context. Nothing else in the context object
203
+ * ever crosses the wire.
204
+ */
205
+ type AgentSharedContext<TContext extends object = Record<string, unknown>> = TContext & {
206
+ page?: () => AgentContext | Promise<AgentContext>;
207
+ };
208
+ type AgentViewMode = "chat-bar" | "floating" | "sidebar";
209
+ type AgentSurfaceVariant = "outline" | "plain" | "surface" | "surface-secondary";
210
+ /**
211
+ * Controls whether an outside interaction closes the floating panel. Matches React
212
+ * Aria Popover: `true` or omitted always closes; `false` never closes.
213
+ */
214
+ type AgentShouldCloseOnInteractOutside = boolean;
215
+ type AgentMarkdownAnimationOptions = {
216
+ animation?: "blurIn" | "fadeIn" | "slideUp" | (string & {});
217
+ duration?: number;
218
+ easing?: string;
219
+ sep?: "char" | "word";
220
+ stagger?: number;
221
+ };
222
+ type AgentMarkdownAnimation = boolean | AgentMarkdownAnimationOptions;
223
+ type AgentMarkdownCaret = "block" | "circle";
224
+ /** Streaming Markdown presentation. Rich renderers are owned by the hosted Agent UI. */
225
+ type AgentMarkdownOptions = {
226
+ /**
227
+ * Animate newly streamed content. Pass `false` to disable text animation.
228
+ * @default {animation: "fadeIn", duration: 160, easing: "ease-out", sep: "word", stagger: 18}
229
+ */
230
+ animated?: AgentMarkdownAnimation;
231
+ /** Streaming caret style. Pass `false` to hide it. @default "block" */
232
+ caret?: AgentMarkdownCaret | false;
233
+ };
234
+ declare const DEFAULT_MARKDOWN_ANIMATION: {
235
+ animation: "fadeIn";
236
+ duration: number;
237
+ easing: string;
238
+ sep: "word";
239
+ stagger: number;
240
+ };
241
+ /** Corner that anchors the launcher button and the floating panel. */
242
+ type AgentLauncherPosition = "bottom-left" | "bottom-right";
243
+ /** Placement of the floating launcher button (visibility is `showLauncher`). */
244
+ type AgentLauncherOptions = {
245
+ /**
246
+ * Fill of the launcher button. Defaults to the accent color; set it when a
247
+ * custom {@link icon} needs a different backdrop. The mark inside gets a
248
+ * contrasting foreground automatically.
249
+ */
250
+ background?: AgentThemeColor;
251
+ /**
252
+ * Image rendered inside the launcher button instead of the built-in spark
253
+ * mark. Use a square asset (70x70 or larger); it is scaled to fit.
254
+ */
255
+ icon?: string;
256
+ /** Icon size in pixels, capped to the launcher bounds. Omitted uses 56% of the button. */
257
+ iconSize?: number;
258
+ /**
259
+ * Pixel offsets from the anchored corner: `x` from the side edge, `y` from
260
+ * the bottom. Defaults to 24 (16 on small screens).
261
+ */
262
+ offset?: {
263
+ x?: number;
264
+ y?: number;
265
+ };
266
+ /** @default "bottom-right" */
267
+ position?: AgentLauncherPosition;
268
+ /**
269
+ * Escape hatch for launcher styling the options above do not cover, applied
270
+ * as inline styles on the button (so it wins over the stylesheet). Prefer the
271
+ * dedicated options where they exist; this is not covered by the embed's
272
+ * visual defaults and can break the button's layout.
273
+ */
274
+ style?: CSSProperties;
275
+ };
276
+ /** Optional hosted-agent capabilities, all off by default. */
277
+ type AgentCapabilities = {
278
+ /**
279
+ * Allow the hosted agent to search for images via web search. Only applies
280
+ * when {@link webSearch} is enabled; defaults to true in that case.
281
+ * @default true
282
+ */
283
+ imageSearch?: boolean;
284
+ /**
285
+ * Allow the hosted agent to include recent news results in web searches.
286
+ * Only applies when {@link webSearch} is enabled and is off by default.
287
+ * @default false
288
+ */
289
+ newsSearch?: boolean;
290
+ /**
291
+ * Allow the hosted agent to search the public web for current information
292
+ * and images. Results are untrusted external content; keep this off when the
293
+ * assistant should only ever answer from your declared client tools.
294
+ * @default false
295
+ */
296
+ webSearch?: boolean;
297
+ };
298
+ /** Browser client-tool approval policy. */
299
+ type AgentPermissionOptions = {
300
+ /**
301
+ * Permission mode used before an end user chooses another mode.
302
+ * `"ask"` gates every client tool, `"auto"` gates only tools marked
303
+ * `needsApproval`, and `"full"` runs client tools without prompting.
304
+ * @default "auto"
305
+ */
306
+ defaultMode?: AgentPermissionMode;
307
+ /**
308
+ * Show the permission picker in the composer, letting the end user switch
309
+ * modes for themselves.
310
+ *
311
+ * This is a privilege boundary, not just a control: it permits the end user
312
+ * to select `"full"` and run every client tool without approval, overriding
313
+ * {@link defaultMode}. Their choice persists for the conversation.
314
+ *
315
+ * The picker only renders when {@link HeroUIAgentProps.tools} is non-empty,
316
+ * since there is nothing to approve otherwise.
317
+ * @default false
318
+ */
319
+ showPicker?: boolean;
320
+ };
321
+ /**
322
+ * Size and expansion of the chat panel. In `floating` mode expansion grows the
323
+ * card; in `sidebar` mode it temporarily fills the viewport. `chat-bar` owns a
324
+ * responsive bottom-centered size. Initial dimensions are ignored in
325
+ * `sidebar` and `chat-bar` modes and below the mobile breakpoint.
326
+ */
327
+ type AgentPanelOptions = {
328
+ /** Mobile presentation for floating/sidebar panels. Defaults to full screen. */
329
+ mobile?: {
330
+ presentation: "fullscreen" | "sheet";
331
+ /** Sheet height, capped to the viewport. Numbers are pixels. @default "75dvh" */
332
+ height?: number | string;
333
+ };
334
+ /**
335
+ * Open the panel expanded. End users can still collapse it unless
336
+ * {@link expandable} is off.
337
+ * @default false
338
+ */
339
+ expanded?: boolean;
340
+ /**
341
+ * Offer the expand control in the panel header. In sidebar mode the expanded
342
+ * panel fills the viewport. Turn it off to pin the panel to one size.
343
+ * @default true
344
+ */
345
+ expandable?: boolean;
346
+ /**
347
+ * Panel height before expanding — a number in pixels or any CSS length.
348
+ * Capped to the viewport.
349
+ * @default "max(420px, 56dvh)"
350
+ */
351
+ initialHeight?: number | string;
352
+ /**
353
+ * Panel width before expanding — a number in pixels or any CSS length.
354
+ * Expanding widens the panel from here. Capped to the viewport.
355
+ * @default 440
356
+ */
357
+ initialWidth?: number | string;
358
+ };
359
+ /** Visual presentation: view mode, theme, panel size, and launcher placement. */
360
+ type AgentAppearance = {
361
+ /** Surface treatment for approval, calendar, commerce, and other response cards. @default "surface" */
362
+ componentSurfaceVariant?: AgentSurfaceVariant;
363
+ /** Where the launcher button (and the floating panel) is anchored. */
364
+ launcher?: AgentLauncherOptions;
365
+ /** Size and expansion of the floating panel. */
366
+ panel?: AgentPanelOptions;
367
+ /**
368
+ * When the visitor interacts outside the floating panel or expanded Chat
369
+ * Bar, whether to close or collapse it. `true` or omitted always closes;
370
+ * `false` keeps it open. Escape and the header action are unchanged.
371
+ */
372
+ shouldCloseOnInteractOutside?: AgentShouldCloseOnInteractOutside;
373
+ /** Surface treatment for charts, tables, maps, and other primary data surfaces. */
374
+ surfaceVariant?: AgentSurfaceVariant;
375
+ theme?: AgentThemeOptions;
376
+ /**
377
+ * How the chat opens: `"floating"` (default) is a floating rounded panel in
378
+ * the corner; `"sidebar"` docks full-height to the right edge; `"chat-bar"`
379
+ * keeps a compact composer centered near the bottom and expands it in place.
380
+ */
381
+ viewMode?: AgentViewMode;
382
+ /**
383
+ * Stacking level of the Agent host. Set this when the Agent must sit below
384
+ * application-owned dialogs or above unusually high application chrome.
385
+ * This sets the public `--ha-z-index` CSS custom property.
386
+ * @default 40
387
+ */
388
+ zIndex?: number;
389
+ };
390
+ /** Message composer settings. */
391
+ type AgentComposerOptions = {
392
+ /**
393
+ * File types end users can attach. Omit to allow every supported type, pass
394
+ * a subset to narrow the picker, or pass `false` to remove attachments.
395
+ * @default all supported attachment types
396
+ */
397
+ attachments?: AgentAttachmentContentType[] | false;
398
+ /**
399
+ * Model used for new turns before an end user chooses another model.
400
+ * When the picker is disabled, this pins every turn to the configured model.
401
+ */
402
+ defaultModel?: AgentModelId;
403
+ /** Show microphone recording and voice transcription controls. @default true */
404
+ dictation?: boolean;
405
+ /**
406
+ * Small verification notice shown below the composer and above the HeroUI
407
+ * attribution. Supports `[label](example.com)` and HTTPS links; bare domains
408
+ * are normalized to HTTPS. Limited to 240 characters. Pass `false` or omit it
409
+ * to hide the notice.
410
+ * @default false
411
+ * @example "Agent may make mistakes. [View terms](https://example.com/terms)"
412
+ */
413
+ disclaimer?: string | false;
414
+ /** Let the end user choose from the hosted agent's allowlisted models. @default false */
415
+ modelPicker?: boolean;
416
+ /** Placeholder shown in the message composer. @default "Ask anything…" */
417
+ placeholder?: string;
418
+ };
419
+ /** The empty-conversation view shown before the first message. */
420
+ type AgentStartScreenOptions = {
421
+ /** Heading shown above the composer. @default "Ask about your data" */
422
+ greeting?: string;
423
+ /** Show and enable `Ctrl+1`…`Ctrl+5` shortcuts for the visible prompts. @default false */
424
+ promptShortcuts?: boolean;
425
+ /** Up to five suggested prompts (each max 160 characters). */
426
+ prompts?: string[];
427
+ /** Supporting text shown below the greeting. Limited to 240 characters. */
428
+ subtitle?: string;
429
+ };
430
+ /** Internal — for HeroUI platform development only. */
431
+ type AgentApiOverrides = {
432
+ baseUrl?: string;
433
+ /** Internal local-development override for the hosted iframe origin. */
434
+ embedOrigin?: string;
435
+ };
436
+ /**
437
+ * Short-lived browser credential returned by the customer's server.
438
+ *
439
+ * Kept in the public bridge so its declarations never refer to private runtime packages.
440
+ */
441
+ type AgentAuthToken = {
442
+ expiresAt: number;
443
+ token: string;
444
+ };
445
+ /** Context supplied whenever the SDK needs a fresh browser credential. */
446
+ type GetAuthTokenContext = {
447
+ signal: AbortSignal;
448
+ anonymousId: string;
449
+ agentId: string;
450
+ };
451
+ type GetAuthToken = (context: GetAuthTokenContext) => Promise<AgentAuthToken>;
452
+ type AgentStatus = "loading" | "authenticating" | "connecting" | "ready" | "generating" | "finishing" | "reconnecting" | "failed";
453
+ type AgentError = {
454
+ category: "authentication" | "connection" | "configuration" | "chunk" | "rate_limit" | "credits" | "deleted" | "approval" | "unknown";
455
+ diagnosticId: string;
456
+ message: string;
457
+ phase: AgentStatus;
458
+ retryable: boolean;
459
+ };
460
+ type HeroUIAgentProps<TContext extends object = Record<string, unknown>> = {
461
+ /** Interface locale, or "auto" to match browser preferences. SDK override > agent default > English. */
462
+ locale?: string;
463
+ /** Copy by language tag, beneath explicit composer/startScreen text. Useful with locale="auto". */
464
+ translations?: Record<string, {
465
+ greeting?: string;
466
+ subtitle?: string;
467
+ placeholder?: string;
468
+ disclaimer?: string | false;
469
+ prompts?: string[];
470
+ }>;
471
+ onError?: (error: AgentError) => void;
472
+ onStatusChange?: (status: AgentStatus) => void;
473
+ /** Called when the visible chat panel opens or closes; preload/readiness is separate. */
474
+ onOpenChange?: (open: boolean) => void;
475
+ /** Internal — for HeroUI platform development only. */
476
+ _api?: AgentApiOverrides;
477
+ appearance?: AgentAppearance;
478
+ capabilities?: AgentCapabilities;
479
+ /** Component export formats to show. Pass `false` to hide export and copy controls. */
480
+ componentExports?: AgentComponentExportFormat[] | false;
481
+ composer?: AgentComposerOptions;
482
+ /**
483
+ * Shared context for client tools; its reserved `page` key supplies the
484
+ * page context sent to the agent. See {@link AgentSharedContext}.
485
+ */
486
+ context?: AgentSharedContext<TContext>;
487
+ /**
488
+ * Fetches a short-lived browser credential from the host application's
489
+ * server. Never expose a workspace API key in browser code.
490
+ */
491
+ getAuthToken: GetAuthToken;
492
+ /** Streaming Markdown animation and caret preferences. */
493
+ markdown?: AgentMarkdownOptions;
494
+ /**
495
+ * Receives end-user ratings for assistant responses. Negative ratings can
496
+ * include structured reasons and an optional comment from the feedback popover.
497
+ */
498
+ onFeedback?: (feedback: AgentResponseFeedback) => Promise<void> | void;
499
+ /**
500
+ * Fires whenever project configuration and the complete composer are ready
501
+ * for the current conversation. Use `useAgent().ready` when a custom launcher
502
+ * also needs the status reactively.
503
+ */
504
+ onReady?: () => void;
505
+ /** Client-tool approval defaults and optional end-user picker. */
506
+ permissions?: AgentPermissionOptions;
507
+ /**
508
+ * Warm the agent before the visitor touches it: fetch the chat engine,
509
+ * configuration, and credentials, then authenticate and preconnect the runtime
510
+ * while the panel is still closed. Work starts immediately and in parallel
511
+ * so readiness follows the launcher as quickly as possible. Opening before
512
+ * then shows the home screen and an editable composer. A conversation is
513
+ * bootstrapped when the visitor submits a message or selects one from history.
514
+ *
515
+ * Set to `false` to defer credentials and the chat engine until the panel is
516
+ * opened. The launcher and its presentation configuration still load.
517
+ * `useAgent().preload()` starts the same warm-up on your signal.
518
+ * @default true
519
+ */
520
+ preload?: boolean;
521
+ agentId: string;
522
+ /**
523
+ * Reopen the panel after a page refresh when it was open before the refresh.
524
+ * The restored panel always starts a new chat instead of resuming the
525
+ * previously active conversation.
526
+ * @default false
527
+ */
528
+ reopenOnRefresh?: boolean;
529
+ /**
530
+ * Return to the start screen whenever the panel is reopened within the same
531
+ * page. A page refresh always starts at home. Conversation history remains
532
+ * available in the picker.
533
+ * @default false
534
+ */
535
+ startNewConversationOnOpen?: boolean;
536
+ /**
537
+ * Apply the appearance saved for this project in the HeroUI dashboard —
538
+ * launcher icon, colors, typography, greeting, subtitle, and suggested prompts —
539
+ * without redeploying.
540
+ *
541
+ * Anything passed in code wins, field by field, so this only fills in what
542
+ * you left unset. Pass `false` to ignore the dashboard entirely and
543
+ * configure the embed exclusively from props.
544
+ * @default true
545
+ */
546
+ remoteConfig?: boolean;
547
+ /**
548
+ * Per-message actions shown under assistant responses: `"copy"` copies the
549
+ * response text, `"feedback"` shows thumbs up/down, `"retry"` regenerates
550
+ * the last response. Pass `false` to hide all actions.
551
+ * @default ["copy", "feedback", "retry"]
552
+ */
553
+ responseActions?: AgentMessageAction[] | false;
554
+ /**
555
+ * Show the floating launcher button when the panel is closed. Set to
556
+ * `false` when opening the agent exclusively through `useAgent()`.
557
+ * @default true
558
+ */
559
+ showLauncher?: boolean;
560
+ /**
561
+ * Show a compact Beta chip in the open panel header, next to the assistant
562
+ * title. Useful while the agent is still stabilizing for end users.
563
+ * @default false
564
+ */
565
+ showBetaBadge?: boolean;
566
+ startScreen?: AgentStartScreenOptions;
567
+ /**
568
+ * Client tools the agent can call in the user's browser. Define with
569
+ * `createToolHelper<Context>()` for typed args and context.
570
+ */
571
+ tools?: ClientTool[];
572
+ };
573
+ type AgentController = {
574
+ hide: () => void;
575
+ /** Start a fresh conversation, optionally submitting its first prompt immediately. */
576
+ newConversation: (prompt?: string) => void;
577
+ /**
578
+ * Warm the agent now, without opening it — the same work the `preload` prop
579
+ * does on its own. Pair it with `preload={false}` to pick the moment from
580
+ * your own signal: a pricing page, a scroll depth, a form the visitor is
581
+ * struggling with. Cheap to call repeatedly; the work happens once.
582
+ */
583
+ preload: () => void;
584
+ /** Whether project configuration and the complete composer are ready to open. */
585
+ ready: boolean;
586
+ refreshAuth: () => void;
587
+ show: () => void;
588
+ shutdown: () => void;
589
+ toggle: () => void;
590
+ };
591
+
592
+ export { type AgentApiOverrides as A, type AgentResponseFeedback as B, type AgentSharedContext as C, type AgentShouldCloseOnInteractOutside as D, type AgentStartScreenOptions as E, type AgentStatus as F, type AgentSurfaceVariant as G, type AgentThemeColor as H, type AgentThemeColors as I, type AgentThemeOptions as J, type AgentTypography as K, type AgentViewMode as L, type ClientTool as M, type ClientToolExecutionContext as N, type ClientToolIcon as O, type ClientToolStatus as P, type ClientToolVisualResult as Q, DEFAULT_MARKDOWN_ANIMATION as R, type GetAuthToken as S, type GetAuthTokenContext as T, type HeroUIAgentProps as U, type UploadAgentDataSourceInput as V, createToolHelper as W, parseClientToolArgs as X, resolveDirectToolAction as Y, type AgentAppearance as a, type AgentAttachmentContentType as b, type AgentAuthToken as c, type AgentCapabilities as d, type AgentColorScheme as e, type AgentComponentExportFormat as f, type AgentComposerOptions as g, type AgentContext as h, type AgentController as i, type AgentDataSource as j, type AgentDataSourceFormat as k, type AgentDesignTheme as l, type AgentError as m, type AgentFeedbackReason as n, type AgentLauncherOptions as o, type AgentLauncherPosition as p, type AgentMarkdownAnimation as q, type AgentMarkdownAnimationOptions as r, type AgentMarkdownCaret as s, type AgentMarkdownOptions as t, type AgentMessageAction as u, type AgentModelId as v, type AgentPanelOptions as w, type AgentPermissionMode as x, type AgentPermissionOptions as y, type AgentRadius as z };
@@ -0,0 +1,5 @@
1
+ declare const HEROUI_AGENT_SDK_VERSION: "1.0.0-beta.11";
2
+ /** Production Agent API origin used when hosts omit `_api.baseUrl` / `apiBaseUrl`. */
3
+ declare const HEROUI_AGENT_API_BASE_URL: "https://api.heroui.pro";
4
+
5
+ export { HEROUI_AGENT_API_BASE_URL as H, HEROUI_AGENT_SDK_VERSION as a };
package/dist/zod.d.ts ADDED
@@ -0,0 +1 @@
1
+ export { z } from 'zod';
package/dist/zod.js ADDED
@@ -0,0 +1,5 @@
1
+ // src/zod.ts
2
+ import { z } from "zod";
3
+ export {
4
+ z
5
+ };