@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.
@@ -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
+ };