@heroui/agent 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/types-BdAn3HPv.d.ts

@@ -0,0 +1,667 @@
+import { CSSProperties } from 'react';
+
+/**
+ * Deliberately Zod-free: `createToolHelper` and these types are re-exported from
+ * the package root, which the panel shell is served from. The manifest
+ * serializer that does need Zod lives in `./client-tools-manifest`.
+ */
+type ClientToolStatus = "input-streaming" | "approval-requested" | "executing" | "completed" | "rejected" | "error";
+/** HeroUI-owned icon rendered by the hosted Agent tool card. */
+type ClientToolIcon = "add" | "database" | "delete" | "edit" | "navigate" | "search" | "sparkles" | "view";
+type ClientToolSchema<TArgs> = {
+    parse: (input: unknown) => TArgs;
+    safeParse: (input: unknown) => unknown;
+};
+type AgentDataSourceFormat = "csv" | "json" | "tsv";
+/** A private, conversation-scoped dataset uploaded by a browser client tool. */
+type AgentDataSource = Readonly<{
+    filename: string;
+    format: AgentDataSourceFormat;
+    id: string;
+    kind: "heroui-agent-data-source";
+    mediaType: "application/json" | "text/csv" | "text/tab-separated-values";
+    size: number;
+    url: string;
+}>;
+type UploadAgentDataSourceInput = Readonly<{
+    /** JSON value, delimited text, Blob, ArrayBuffer, or byte array. */
+    data: unknown;
+    filename?: string;
+    format?: AgentDataSourceFormat;
+}>;
+/**
+ * Stable identity for one agent-initiated browser tool effect. Pass
+ * `idempotencyKey` through to mutation APIs so an ambiguous network retry can
+ * return the original result instead of applying the side effect twice.
+ */
+type ClientToolExecutionContext = Readonly<{
+    conversationId: string;
+    idempotencyKey: string;
+    toolCallId: string;
+    /** Upload a large result without placing its bytes in the 64 KiB tool receipt. */
+    uploadDataSource: (input: UploadAgentDataSourceInput) => Promise<AgentDataSource>;
+}>;
+/**
+ * A tool the agent can call in the user's browser. Execution stays in the
+ * customer page; the hosted iframe receives only its declarative manifest and
+ * a validated result.
+ */
+type ClientTool<TArgs = any, TContext = any> = {
+    description: string;
+    /** Human-readable name shown in the default tool card. Defaults to `name`. */
+    displayName?: string;
+    execute: (args: TArgs, context: TContext, execution: ClientToolExecutionContext) => Promise<unknown> | unknown;
+    /** HeroUI-owned icon rendered by the hosted tool card. */
+    icon?: ClientToolIcon;
+    iconColor?: string;
+    name: string;
+    /** When true, the user must approve the call before `execute` runs. */
+    needsApproval?: boolean;
+    /** Zod schema (typed) or raw JSON Schema object for the tool parameters. */
+    parameters: ClientToolSchema<TArgs> | Record<string, unknown>;
+};
+/**
+ * Returns a type-safe tool factory bound to your shared context type:
+ *
+ * ```ts
+ * type AppContext = {apiClient: ApiClient};
+ * const tool = createToolHelper<AppContext>();
+ * const tools = [tool({name: "search_users", parameters: z.object({...}), execute: (args, ctx) => ...})];
+ * ```
+ */
+declare function createToolHelper<TContext>(): <TArgs>(definition: ClientTool<TArgs, TContext>) => ClientTool<TArgs, TContext>;
+/** Parses model-provided args with the local Zod schema when available. */
+declare function parseClientToolArgs(tool: ClientTool, input: unknown): unknown;
+/**
+ * Resolves a component "tool" action (a rendered button's toolCall) to the
+ * client tool it may execute directly in the page. Unknown and approval-gated
+ * tools return null — those actions fall back to their composer prompt so
+ * nothing ever runs without the user seeing it first.
+ */
+declare function resolveDirectToolAction(tools: ReadonlyMap<string, ClientTool>, toolName: string): ClientTool | null;
+
+/** Maximum number of files accepted on one HeroUI Agent message. */
+declare const HEROUI_AGENT_MAX_ATTACHMENTS = 5;
+/** Maximum stored size for one HeroUI Agent attachment (10 MiB). */
+declare const HEROUI_AGENT_ATTACHMENT_MAX_BYTES: number;
+/**
+ * File types that the hosted model pipeline can process consistently.
+ *
+ * SVG is intentionally excluded because it can carry active content. Hosted
+ * document parsing handles the remaining office and publishing formats.
+ */
+declare const HEROUI_AGENT_ATTACHMENT_EXTENSION_BY_CONTENT_TYPE: {
+    readonly "application/epub+zip": "epub";
+    readonly "application/json": "json";
+    readonly "application/msword": "doc";
+    readonly "application/pdf": "pdf";
+    readonly "application/rtf": "rtf";
+    readonly "application/vnd.ms-excel": "xls";
+    readonly "application/vnd.ms-excel.sheet.binary.macroenabled.12": "xlsb";
+    readonly "application/vnd.ms-excel.sheet.macroenabled.12": "xlsm";
+    readonly "application/vnd.ms-powerpoint": "ppt";
+    readonly "application/vnd.ms-powerpoint.presentation.macroenabled.12": "pptm";
+    readonly "application/vnd.ms-word.document.macroenabled.12": "docm";
+    readonly "application/vnd.oasis.opendocument.presentation": "odp";
+    readonly "application/vnd.oasis.opendocument.spreadsheet": "ods";
+    readonly "application/vnd.oasis.opendocument.text": "odt";
+    readonly "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx";
+    readonly "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx";
+    readonly "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx";
+    readonly "image/gif": "gif";
+    readonly "image/jpeg": "jpg";
+    readonly "image/png": "png";
+    readonly "image/webp": "webp";
+    readonly "text/csv": "csv";
+    readonly "text/html": "html";
+    readonly "text/markdown": "md";
+    readonly "text/plain": "txt";
+    readonly "text/rtf": "rtf";
+    readonly "text/tab-separated-values": "tsv";
+};
+type HeroUIAgentAttachmentContentType = keyof typeof HEROUI_AGENT_ATTACHMENT_EXTENSION_BY_CONTENT_TYPE;
+declare const HEROUI_AGENT_ATTACHMENT_CONTENT_TYPES: readonly ("application/json" | "text/csv" | "text/tab-separated-values" | "application/epub+zip" | "application/msword" | "application/pdf" | "application/rtf" | "application/vnd.ms-excel" | "application/vnd.ms-excel.sheet.binary.macroenabled.12" | "application/vnd.ms-excel.sheet.macroenabled.12" | "application/vnd.ms-powerpoint" | "application/vnd.ms-powerpoint.presentation.macroenabled.12" | "application/vnd.ms-word.document.macroenabled.12" | "application/vnd.oasis.opendocument.presentation" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/gif" | "image/jpeg" | "image/png" | "image/webp" | "text/html" | "text/markdown" | "text/plain" | "text/rtf")[];
+declare const HEROUI_AGENT_ATTACHMENT_ACCEPT: string;
+declare const HEROUI_AGENT_ATTACHMENT_CONTENT_TYPE_BY_EXTENSION: Readonly<Record<string, "application/json" | "text/csv" | "text/tab-separated-values" | "application/epub+zip" | "application/msword" | "application/pdf" | "application/rtf" | "application/vnd.ms-excel" | "application/vnd.ms-excel.sheet.binary.macroenabled.12" | "application/vnd.ms-excel.sheet.macroenabled.12" | "application/vnd.ms-powerpoint" | "application/vnd.ms-powerpoint.presentation.macroenabled.12" | "application/vnd.ms-word.document.macroenabled.12" | "application/vnd.oasis.opendocument.presentation" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/gif" | "image/jpeg" | "image/png" | "image/webp" | "text/html" | "text/markdown" | "text/plain" | "text/rtf">>;
+declare const HEROUI_AGENT_TEXT_ATTACHMENT_CONTENT_TYPES: ReadonlySet<string>;
+declare function isHeroUIAgentAttachmentContentType(value: string): value is HeroUIAgentAttachmentContentType;
+/** Browsers sometimes omit Office MIME types; fall back to the file extension. */
+declare function resolveHeroUIAgentAttachmentContentType(contentType: string, filename: string): HeroUIAgentAttachmentContentType | null;
+
+/**
+ * Deliberately Zod-free: the model catalogue is re-exported from the package
+ * root, so importing Zod here would pull the whole validation library into the
+ * panel shell's first-paint graph. The matching schema lives in
+ * `./models.schema`, which only server and contract consumers need.
+ */
+/** Model ids the hosted agent accepts from the browser picker. */
+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.7-flash", "anthropic/claude-sonnet-5", "anthropic/claude-opus-4.8"];
+type AgentModelId = (typeof AGENT_MODEL_IDS)[number];
+/**
+ * Retired ids mapped to their replacement. Model ids are a public part of the
+ * embed API — a customer pins one in their own code and projects store one as
+ * their default — so a retired id keeps resolving instead of failing the
+ * session with an "Invalid agent model" error.
+ */
+declare const LEGACY_AGENT_MODEL_IDS: Record<string, AgentModelId>;
+/** Resolves a possibly-retired model id to the id the runtime should use. */
+declare function resolveAgentModelId(value: string): string;
+type AgentModelTier = "codegen" | "complex" | "light";
+type AgentModelOption = {
+    description: string;
+    id: AgentModelId;
+    label: string;
+    provider: "Anthropic" | "Google" | "Moonshot AI" | "OpenAI";
+    tier: AgentModelTier;
+};
+/**
+ * Recommended default selected when the optional picker first opens. Gemini 3.7 Flash
+ * matches the hosted runtime's baked-in default (`DEFAULT_CHAT_MODEL_IDS.herouiAgent`),
+ * so what users see in the picker is what actually runs by default.
+ */
+declare const DEFAULT_AGENT_PICKER_MODEL_ID = "google/gemini-3.7-flash";
+/**
+ * Small, tool-capable model catalog for HeroUI Agent. These ids are the
+ * server-side allowlist as well as the browser picker source of truth.
+ */
+declare const AGENT_MODEL_OPTIONS: readonly [{
+    readonly description: "Flagship model for coding, reasoning, and knowledge work";
+    readonly id: "moonshotai/Kimi-K3";
+    readonly label: "Kimi K3";
+    readonly provider: "Moonshot AI";
+    readonly tier: "light";
+}, {
+    readonly description: "Fast answers and lightweight agent workflows";
+    readonly id: "openai/gpt-5.6-luna";
+    readonly label: "GPT-5.6 Luna";
+    readonly provider: "OpenAI";
+    readonly tier: "light";
+}, {
+    readonly description: "Balanced reasoning for everyday agent tasks";
+    readonly id: "openai/gpt-5.6-terra";
+    readonly label: "GPT-5.6 Terra";
+    readonly provider: "OpenAI";
+    readonly tier: "codegen";
+}, {
+    readonly description: "Deep reasoning for complex, multi-step analysis";
+    readonly id: "openai/gpt-5.6-sol";
+    readonly label: "GPT-5.6 Sol";
+    readonly provider: "OpenAI";
+    readonly tier: "complex";
+}, {
+    readonly description: "Fast multimodal analysis with a large context window";
+    readonly id: "google/gemini-3.7-flash";
+    readonly label: "Gemini 3.7 Flash";
+    readonly provider: "Google";
+    readonly tier: "light";
+}, {
+    readonly description: "Strong agentic reasoning and polished UI decisions";
+    readonly id: "anthropic/claude-sonnet-5";
+    readonly label: "Claude Sonnet 5";
+    readonly provider: "Anthropic";
+    readonly tier: "codegen";
+}, {
+    readonly description: "Highest-capability Claude for difficult research and analysis";
+    readonly id: "anthropic/claude-opus-4.8";
+    readonly label: "Claude Opus 4.8";
+    readonly provider: "Anthropic";
+    readonly tier: "complex";
+}];
+declare function isAgentModelId(value: unknown): value is AgentModelId;
+/** Unknown/env-overridden models keep the hosted agent's historical light tier. */
+declare function getAgentModelTier(modelId?: string): AgentModelTier;
+
+/**
+ * Light/dark color scheme selection for the embed. `"system"` follows the
+ * OS preference and updates live when it changes.
+ */
+type AgentColorScheme = "dark" | "light" | "system";
+/**
+ * A theme color value: one CSS color applied to both schemes, or separate
+ * values per scheme. Tokens left unset fall back to the built-in defaults of
+ * each scheme, so overriding a light color never degrades dark mode.
+ */
+type AgentThemeColor = string | {
+    dark?: string;
+    light?: string;
+};
+/** Corner rounding preset applied across the embed surface and fields. */
+type AgentRadius = "pill" | "round" | "sharp" | "soft";
+/**
+ * The seven high-impact color tokens. Everything else in the embed
+ * (borders, shadows, chart palettes) derives from these and from the
+ * built-in scheme defaults.
+ */
+type AgentThemeColors = {
+    /** Primary action and highlight color. Chart palettes derive from it. */
+    accent?: AgentThemeColor;
+    /** Chat panel background. */
+    background?: AgentThemeColor;
+    /** Primary text color. */
+    foreground?: AgentThemeColor;
+    /** Dropdown and popover surface color. */
+    overlay?: AgentThemeColor;
+    /** Card surface color. */
+    surface?: AgentThemeColor;
+    /** Secondary surface color (chips, muted fills). */
+    surfaceSecondary?: AgentThemeColor;
+    /** Tooltip surface color. Text contrast is derived automatically. */
+    tooltip?: AgentThemeColor;
+};
+type AgentTypography = {
+    /**
+     * Base font size in pixels (clamped to 12–18).
+     * @default 14
+     */
+    baseSize?: number;
+    /** CSS font family stack, e.g. `"Geist, sans-serif"`. */
+    fontFamily?: string;
+};
+/**
+ * HeroUI Pro theme variant applied to the agent surface.
+ *
+ * Hosted Agent deployments include all supported variants; the selected one
+ * is activated inside the iframe.
+ */
+type AgentDesignTheme = "base" | "brutalism" | "glass" | "mouve";
+declare const AGENT_DESIGN_THEMES: readonly AgentDesignTheme[];
+/**
+ * Intentionally small theme surface: one color scheme, one Pro variant, four
+ * radius presets, seven color tokens, and basic typography. No named themes,
+ * extend chains, or per-component tokens.
+ */
+type AgentThemeOptions = {
+    /** @default "system" */
+    colorScheme?: AgentColorScheme;
+    colors?: AgentThemeColors;
+    /**
+     * HeroUI Pro theme variant rendered by the hosted Agent.
+     * @default "base"
+     */
+    designTheme?: AgentDesignTheme;
+    /** @default "round" */
+    radius?: AgentRadius;
+    typography?: AgentTypography;
+};
+
+type AgentComponentExportFormat = "csv" | "png" | "svg";
+type AgentPermissionMode = "ask" | "auto" | "full";
+/** MIME type accepted by the hosted HeroUI Agent attachment pipeline. */
+type AgentAttachmentContentType = HeroUIAgentAttachmentContentType;
+type AgentMessageAction = "copy" | "feedback" | "retry";
+type AgentFeedbackReason = "did_not_follow_instructions" | "incomplete" | "incorrect" | "not_relevant" | "other" | "unclear";
+type AgentResponseFeedback = {
+    /** Optional free-form context supplied by the end user. */
+    comment?: string;
+    conversationId: string;
+    messageId: string;
+    rating: "negative" | "positive";
+    /** Structured reasons selected for negative feedback. Empty for positive feedback. */
+    reasons: AgentFeedbackReason[];
+};
+type AgentContext = Record<string, unknown>;
+/**
+ * The single shared context object. It is passed as the second argument to
+ * every client tool's `execute` — API clients, user info, state setters.
+ * Anything goes; it never leaves the browser.
+ *
+ * One key is reserved: `page`. When present, the SDK calls it on every turn
+ * and sends its JSON-serializable return value (route, filters, selection —
+ * max 16KB) to the agent as page context. Nothing else in the context object
+ * ever crosses the wire.
+ */
+type AgentSharedContext = {
+    page?: () => AgentContext | Promise<AgentContext>;
+} & Record<string, unknown>;
+type AgentViewMode = "floating" | "sidebar";
+type AgentSurfaceVariant = "outline" | "plain" | "surface" | "surface-secondary";
+/**
+ * Controls whether an outside interaction closes the floating panel. Matches React
+ * Aria Popover: `true` or omitted always closes; `false` never closes.
+ */
+type AgentShouldCloseOnInteractOutside = boolean;
+type AgentMarkdownAnimationOptions = {
+    animation?: "blurIn" | "fadeIn" | "slideUp" | (string & {});
+    duration?: number;
+    easing?: string;
+    sep?: "char" | "word";
+    stagger?: number;
+};
+type AgentMarkdownAnimation = boolean | AgentMarkdownAnimationOptions;
+type AgentMarkdownCaret = "block" | "circle";
+/** Streaming Markdown presentation. Rich renderers are owned by the hosted Agent UI. */
+type AgentMarkdownOptions = {
+    /**
+     * Animate newly streamed content. Pass `false` to disable text animation.
+     * @default {animation: "fadeIn", duration: 160, easing: "ease-out", sep: "word", stagger: 18}
+     */
+    animated?: AgentMarkdownAnimation;
+    /** Streaming caret style. Pass `false` to hide it. @default "block" */
+    caret?: AgentMarkdownCaret | false;
+};
+declare const DEFAULT_MARKDOWN_ANIMATION: {
+    animation: "fadeIn";
+    duration: number;
+    easing: string;
+    sep: "word";
+    stagger: number;
+};
+/** Corner that anchors the launcher button and the floating panel. */
+type AgentLauncherPosition = "bottom-left" | "bottom-right";
+/** Placement of the floating launcher button (visibility is `showLauncher`). */
+type AgentLauncherOptions = {
+    /**
+     * Fill of the launcher button. Defaults to the accent color; set it when a
+     * custom {@link icon} needs a different backdrop. The mark inside gets a
+     * contrasting foreground automatically.
+     */
+    background?: AgentThemeColor;
+    /**
+     * Image rendered inside the launcher button instead of the built-in spark
+     * mark. Use a square asset (70x70 or larger); it is scaled to fit.
+     */
+    icon?: string;
+    /**
+     * Pixel offsets from the anchored corner: `x` from the side edge, `y` from
+     * the bottom. Defaults to 24 (16 on small screens).
+     */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /** @default "bottom-right" */
+    position?: AgentLauncherPosition;
+    /**
+     * Escape hatch for launcher styling the options above do not cover, applied
+     * as inline styles on the button (so it wins over the stylesheet). Prefer the
+     * dedicated options where they exist; this is not covered by the embed's
+     * visual defaults and can break the button's layout.
+     */
+    style?: CSSProperties;
+};
+/** Optional hosted-agent capabilities, all off by default. */
+type AgentCapabilities = {
+    /**
+     * Allow the hosted agent to search for images via web search. Only applies
+     * when {@link webSearch} is enabled; defaults to true in that case.
+     * @default true
+     */
+    imageSearch?: boolean;
+    /**
+     * Allow the hosted agent to include recent news results in web searches.
+     * Only applies when {@link webSearch} is enabled and is off by default.
+     * @default false
+     */
+    newsSearch?: boolean;
+    /**
+     * Allow the hosted agent to search the public web for current information
+     * and images. Results are untrusted external content; keep this off when the
+     * assistant should only ever answer from your declared client tools.
+     * @default false
+     */
+    webSearch?: boolean;
+};
+/** Browser client-tool approval policy. */
+type AgentPermissionOptions = {
+    /**
+     * Permission mode used before an end user chooses another mode.
+     * `"ask"` gates every client tool, `"auto"` gates only tools marked
+     * `needsApproval`, and `"full"` runs client tools without prompting.
+     * @default "auto"
+     */
+    defaultMode?: AgentPermissionMode;
+    /**
+     * Show the permission picker in the composer, letting the end user switch
+     * modes for themselves.
+     *
+     * This is a privilege boundary, not just a control: it permits the end user
+     * to select `"full"` and run every client tool without approval, overriding
+     * {@link defaultMode}. Their choice persists for the conversation.
+     *
+     * The picker only renders when {@link HeroUIAgentProps.tools} is non-empty,
+     * since there is nothing to approve otherwise.
+     * @default false
+     */
+    showPicker?: boolean;
+};
+/**
+ * Size and expansion of the chat panel. In `floating` mode expansion grows the
+ * card; in `sidebar` mode it temporarily fills the viewport. Initial dimensions
+ * are ignored in `sidebar` mode and below the mobile breakpoint.
+ */
+type AgentPanelOptions = {
+    /**
+     * Open the panel expanded. End users can still collapse it unless
+     * {@link expandable} is off.
+     * @default false
+     */
+    expanded?: boolean;
+    /**
+     * Offer the expand control in the panel header. In sidebar mode the expanded
+     * panel fills the viewport. Turn it off to pin the panel to one size.
+     * @default true
+     */
+    expandable?: boolean;
+    /**
+     * Panel height before expanding — a number in pixels or any CSS length.
+     * Capped to the viewport.
+     * @default "max(420px, 56dvh)"
+     */
+    initialHeight?: number | string;
+    /**
+     * Panel width before expanding — a number in pixels or any CSS length.
+     * Expanding widens the panel from here. Capped to the viewport.
+     * @default 440
+     */
+    initialWidth?: number | string;
+};
+/** Visual presentation: view mode, theme, panel size, and launcher placement. */
+type AgentAppearance = {
+    /** Surface treatment for approval, calendar, commerce, and other response cards. @default "surface" */
+    componentSurfaceVariant?: AgentSurfaceVariant;
+    /** Where the launcher button (and the floating panel) is anchored. */
+    launcher?: AgentLauncherOptions;
+    /** Size and expansion of the floating panel. */
+    panel?: AgentPanelOptions;
+    /**
+     * When the visitor interacts outside the floating panel, whether to close it.
+     * Only applies in `viewMode: "floating"`. `true` or omitted always closes;
+     * `false` never closes on outside interact. Escape and the header close
+     * button are unchanged.
+     */
+    shouldCloseOnInteractOutside?: AgentShouldCloseOnInteractOutside;
+    /** Surface treatment for charts, tables, maps, and other primary data surfaces. */
+    surfaceVariant?: AgentSurfaceVariant;
+    theme?: AgentThemeOptions;
+    /**
+     * How the chat opens: `"floating"` (default) is a floating rounded panel in
+     * the corner; `"sidebar"` docks full-height to the right edge of the page.
+     */
+    viewMode?: AgentViewMode;
+    /**
+     * Stacking level of the Agent host. Set this when the Agent must sit below
+     * application-owned dialogs or above unusually high application chrome.
+     * This sets the public `--ha-z-index` CSS custom property.
+     * @default 40
+     */
+    zIndex?: number;
+};
+/** Message composer settings. */
+type AgentComposerOptions = {
+    /**
+     * File types end users can attach. Omit to allow every supported type, pass
+     * a subset to narrow the picker, or pass `false` to remove attachments.
+     * @default all supported attachment types
+     */
+    attachments?: AgentAttachmentContentType[] | false;
+    /**
+     * Model used for new turns before an end user chooses another model.
+     * When the picker is disabled, this pins every turn to the configured model.
+     */
+    defaultModel?: AgentModelId;
+    /** Show microphone recording and voice transcription controls. @default true */
+    dictation?: boolean;
+    /**
+     * Small verification notice shown below the composer and above the HeroUI
+     * attribution. Supports `[label](example.com)` and HTTPS links; bare domains
+     * are normalized to HTTPS. Limited to 240 characters. Pass `false` or omit it
+     * to hide the notice.
+     * @default false
+     * @example "Agent may make mistakes. [View terms](https://example.com/terms)"
+     */
+    disclaimer?: string | false;
+    /** Let the end user choose from the hosted agent's allowlisted models. @default false */
+    modelPicker?: boolean;
+    /** Placeholder shown in the message composer. @default "Ask anything…" */
+    placeholder?: string;
+};
+/** The empty-conversation view shown before the first message. */
+type AgentStartScreenOptions = {
+    /** Heading shown above the composer. @default "Ask about your data" */
+    greeting?: string;
+    /** Show and enable `Ctrl+1`…`Ctrl+5` shortcuts for the visible prompts. @default false */
+    promptShortcuts?: boolean;
+    /** Up to five suggested prompts (each max 160 characters). */
+    prompts?: string[];
+    /** Supporting text shown below the greeting. Limited to 240 characters. */
+    subtitle?: string;
+};
+/** Internal — for HeroUI platform development only. */
+type AgentApiOverrides = {
+    baseUrl?: string;
+    /** Internal local-development override for the hosted iframe origin. */
+    embedOrigin?: string;
+};
+/**
+ * Short-lived browser credential returned by the customer's server.
+ *
+ * Kept in the public bridge so its declarations never refer to private runtime packages.
+ */
+type AgentAuthToken = {
+    expiresAt: number;
+    token: string;
+};
+/** Context supplied whenever the SDK needs a fresh browser credential. */
+type GetAuthTokenContext = {
+    anonymousId: string;
+    agentId: string;
+};
+type GetAuthToken = (context: GetAuthTokenContext) => Promise<AgentAuthToken>;
+type HeroUIAgentProps = {
+    /** Internal — for HeroUI platform development only. */
+    _api?: AgentApiOverrides;
+    appearance?: AgentAppearance;
+    capabilities?: AgentCapabilities;
+    /** Component export formats to show. Pass `false` to hide export and copy controls. */
+    componentExports?: AgentComponentExportFormat[] | false;
+    composer?: AgentComposerOptions;
+    /**
+     * Shared context for client tools; its reserved `page` key supplies the
+     * page context sent to the agent. See {@link AgentSharedContext}.
+     */
+    context?: AgentSharedContext;
+    /**
+     * Fetches a short-lived browser credential from the host application's
+     * server. Never expose a HeroUI Agent API key in browser code.
+     */
+    getAuthToken: GetAuthToken;
+    /** Streaming Markdown animation and caret preferences. */
+    markdown?: AgentMarkdownOptions;
+    /**
+     * Receives end-user ratings for assistant responses. Negative ratings can
+     * include structured reasons and an optional comment from the feedback popover.
+     */
+    onFeedback?: (feedback: AgentResponseFeedback) => Promise<void> | void;
+    /**
+     * Fires whenever project configuration and the complete composer are ready
+     * for the current conversation. Use `useAgent().ready` when a custom launcher
+     * also needs the status reactively.
+     */
+    onReady?: () => void;
+    /** Client-tool approval defaults and optional end-user picker. */
+    permissions?: AgentPermissionOptions;
+    /**
+     * Warm the agent before the visitor touches it: fetch the chat engine,
+     * configuration, and credentials, then bootstrap and preconnect the runtime
+     * while the panel is still closed. Work starts immediately and in parallel
+     * so readiness follows the launcher as quickly as possible. Opening before
+     * then shows the Agent shell with a loading state.
+     *
+     * Set to `false` to request nothing until the panel is opened. Worth doing
+     * when most visitors never open the agent, or on pages where you want to
+     * choose the moment yourself — `useAgent().preload()` runs the same warm-up
+     * on your signal.
+     * @default true
+     */
+    preload?: boolean;
+    agentId: string;
+    /**
+     * Reopen the panel after a page refresh when it was open before the refresh.
+     * The restored panel always starts a new chat instead of resuming the
+     * previously active conversation.
+     * @default false
+     */
+    reopenOnRefresh?: boolean;
+    /**
+     * Open the panel on the start screen instead of restoring the most recently
+     * active conversation. Conversation history remains available in the picker.
+     * @default false
+     */
+    startNewConversationOnOpen?: boolean;
+    /**
+     * Apply the appearance saved for this project in the HeroUI dashboard —
+     * launcher icon, colors, typography, greeting, subtitle, and suggested prompts —
+     * without redeploying.
+     *
+     * Anything passed in code wins, field by field, so this only fills in what
+     * you left unset. Pass `false` to ignore the dashboard entirely and
+     * configure the embed exclusively from props.
+     * @default true
+     */
+    remoteConfig?: boolean;
+    /**
+     * Per-message actions shown under assistant responses: `"copy"` copies the
+     * response text, `"feedback"` shows thumbs up/down, `"retry"` regenerates
+     * the last response. Pass `false` to hide all actions.
+     * @default ["copy", "feedback", "retry"]
+     */
+    responseActions?: AgentMessageAction[] | false;
+    /**
+     * Show the floating launcher button when the panel is closed. Set to
+     * `false` when opening the agent exclusively through `useAgent()`.
+     * @default true
+     */
+    showLauncher?: boolean;
+    /**
+     * Show a compact Beta chip in the open panel header, next to the assistant
+     * title. Useful while the agent is still stabilizing for end users.
+     * @default false
+     */
+    showBetaBadge?: boolean;
+    startScreen?: AgentStartScreenOptions;
+    /**
+     * Client tools the agent can call in the user's browser. Define with
+     * `createToolHelper<Context>()` for typed args and context.
+     */
+    tools?: ClientTool[];
+};
+type AgentController = {
+    hide: () => void;
+    /** Start a fresh conversation, optionally submitting its first prompt immediately. */
+    newConversation: (prompt?: string) => void;
+    /**
+     * Warm the agent now, without opening it — the same work the `preload` prop
+     * does on its own. Pair it with `preload={false}` to pick the moment from
+     * your own signal: a pricing page, a scroll depth, a form the visitor is
+     * struggling with. Cheap to call repeatedly; the work happens once.
+     */
+    preload: () => void;
+    /** Whether project configuration and the complete composer are ready to open. */
+    ready: boolean;
+    refreshAuth: () => void;
+    show: () => void;
+    shutdown: () => void;
+    toggle: () => void;
+};
+
+export { HEROUI_AGENT_ATTACHMENT_MAX_BYTES as $, AGENT_DESIGN_THEMES as A, type AgentPanelOptions as B, type AgentPermissionMode as C, type AgentPermissionOptions as D, type AgentRadius as E, type AgentResponseFeedback as F, type AgentSharedContext as G, type AgentShouldCloseOnInteractOutside as H, type AgentStartScreenOptions as I, type AgentSurfaceVariant as J, type AgentThemeColor as K, type AgentThemeColors as L, type AgentThemeOptions as M, type AgentTypography as N, type AgentViewMode as O, type ClientTool as P, type ClientToolExecutionContext as Q, type ClientToolIcon as R, type ClientToolStatus as S, DEFAULT_AGENT_PICKER_MODEL_ID as T, DEFAULT_MARKDOWN_ANIMATION as U, type GetAuthToken as V, type GetAuthTokenContext as W, HEROUI_AGENT_ATTACHMENT_ACCEPT as X, HEROUI_AGENT_ATTACHMENT_CONTENT_TYPES as Y, HEROUI_AGENT_ATTACHMENT_CONTENT_TYPE_BY_EXTENSION as Z, HEROUI_AGENT_ATTACHMENT_EXTENSION_BY_CONTENT_TYPE as _, AGENT_MODEL_IDS as a, HEROUI_AGENT_MAX_ATTACHMENTS as a0, HEROUI_AGENT_TEXT_ATTACHMENT_CONTENT_TYPES as a1, type HeroUIAgentAttachmentContentType as a2, type HeroUIAgentProps as a3, LEGACY_AGENT_MODEL_IDS as a4, type UploadAgentDataSourceInput as a5, createToolHelper as a6, getAgentModelTier as a7, isAgentModelId as a8, isHeroUIAgentAttachmentContentType as a9, parseClientToolArgs as aa, resolveAgentModelId as ab, resolveDirectToolAction as ac, resolveHeroUIAgentAttachmentContentType as ad, AGENT_MODEL_OPTIONS as b, type AgentApiOverrides as c, type AgentAppearance as d, type AgentAttachmentContentType as e, type AgentAuthToken as f, type AgentCapabilities as g, type AgentColorScheme as h, type AgentComponentExportFormat as i, type AgentComposerOptions as j, type AgentContext as k, type AgentController as l, type AgentDataSource as m, type AgentDataSourceFormat as n, type AgentDesignTheme as o, type AgentFeedbackReason as p, type AgentLauncherOptions as q, type AgentLauncherPosition as r, type AgentMarkdownAnimation as s, type AgentMarkdownAnimationOptions as t, type AgentMarkdownCaret as u, type AgentMarkdownOptions as v, type AgentMessageAction as w, type AgentModelId as x, type AgentModelOption as y, type AgentModelTier as z };

package/dist/version-CIfRqjWe.d.ts

@@ -0,0 +1,5 @@
+declare const HEROUI_AGENT_SDK_VERSION: "1.0.0-beta.5";
+/** Production Agent API origin used when hosts omit `_api.baseUrl` / `apiBaseUrl`. */
+declare const HEROUI_AGENT_API_BASE_URL: "https://api.heroui.pro";
+
+export { HEROUI_AGENT_API_BASE_URL as H, HEROUI_AGENT_SDK_VERSION as a };