@heroui/agent 0.2.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 0.2.0-beta.1
+
+- Add the `kpi-grid` component: up to four headline KPIs, each pairing its value and change with a
+  sparkline of its own history. `renderComponent` can build one straight from a multi-period dataset,
+  taking each numeric column as one KPI. `metric-grid` stays for figures with no history to plot, and
+  the agent is instructed never to fabricate a trend to reach for the richer card.
+- Fold `renderUI` into `composeUI`, which now accepts either a single component or a layout tree as
+  its root. The component union is no longer declared to the model as a tool schema: it reads a
+  compact kind catalog and fetches the props it needs with `getComponentSchema`, which cut ~300 KB
+  (~76K tokens) of JSON Schema off every rendering request. `renderUI` and the `loadUIRenderers`
+  deferral it needed are gone; only `loadUIRenderers` stays reserved for stored-conversation safety.
+- Promote fourteen polished Storybook response compositions to validated Agent UI kinds, including
+  current weather, forecasts, flights, events, rides, playlists, commerce, messages, player stats,
+  notifications, and product-signal tabs.
+- Bump the Agent protocol to version 4 so older embeds receive an explicit upgrade response instead
+  of silently dropping the new component kinds.
+- Require a `getAuthToken` callback alongside `agentId` for React, Next.js, and
+  CDN integrations.
+- Exchange the project API key only from a server when minting a short-lived browser token.
+  Protocol version 3 includes its API key id in the JWT so revoking a key immediately invalidates
+  its sessions.
+- Add dashboard-managed projects, versioned playground configuration, and deterministic
+  server-authenticated setup code generation.
+- Identify signed-in end users: `createAuthToken` accepts the browser's `anonymousId` alongside an
+  identified `identity`, moving conversations started before login onto that person. Identified
+  users now see their history on any device they sign in from.
+- Add `useAgent().refreshAuth()` to mint a credential for the person who just signed in.
+  `shutdown()` now also drops the cached credential and the browser's anonymous id, so a shared
+  device does not attribute the next visitor to the previous user.
+- Reject placeholder identity values such as `anonymous`, `undefined`, and `null`, which would
+  otherwise collapse unrelated visitors into one person.
+
+## 0.1.0-beta.0
+
+- Initial public beta of the React provider, vanilla loader, server token client, approval-gated
+  actions, generated calculation sandbox, durable streaming transport, and validated generative UI
+  components.
+- Generative UI renders through three runtime tools — `renderComponent` (dataset charts, tables,
+  metrics, comparisons), `renderUI` (record cards, timelines, forms, follow-ups, dashboards), and
+  `composeUI` (bounded layout composition) — all constrained to one validated component union.
+- Semantic card hierarchy plus details/compact/media record layouts, meter lists, task progress
+  states, typed number/date-range/time/boolean form fields, prompt-aware actions, and
+  runtime-attested source links for web-backed responses.
+- Per-browser conversation history with an in-embed conversation picker and a resizable sidebar
+  view mode.
+- Embed styles ship through the `@heroui/agent/css` package export and must be imported by React
+  applications; the CDN loader adds the same compiled stylesheet automatically.
+- Grouped configuration props: `appearance` (view mode plus a small theme surface with color
+  scheme, radius, seven color tokens, and typography), `composer`, `startScreen` (greeting and
+  prompts), `capabilities`, `permissions`, `componentExports`, `responseActions`, and
+  `showLauncher` — with `agentId`, `tools`, and `context` at the root. Permission modes can ask
+  before every client tool, respect per-tool `needsApproval` flags, or run declared tools without
+  prompting; the end-user picker is host opt-in.
+
+### Known limitations
+
+- Invite-only manual provisioning, English-only UI, a fixed validated component union, and
+  per-browser conversation history (no cross-device identity).
+- No background mutations, MCP/OpenAPI import, custom component registration, self-hosting, or
+  public pricing during the beta.
+- Exact compatibility is guaranteed only for protocol version 4 and this prerelease; review this
+  changelog before upgrading to another beta.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeroUI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+![hero](https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/npm-packages/agents/heroui-agents@2x.jpg)
+
+# HeroUI Agents SDK
+
+Embed a hosted generative-UI agent in your React app with [`@heroui/agent`](https://www.heroui.com/agents). Declare typed client tools that read your data — the hosted runtime plans the answer, runs calculations in a sandbox, and streams back charts, tables, and metrics.
+
+## Installation
+
+```bash
+npm install @heroui/agent@beta
+```
+
+Import the stylesheet once:
+
+```css
+@import "@heroui/agent/css";
+```
+
+## Usage
+
+```tsx
+import {HeroUIAgent} from "@heroui/agent/next";
+
+export function AppAgent() {
+  return (
+    <HeroUIAgent
+      agentId="proj_..."
+      getAuthToken={async (context) => {
+        const response = await fetch("/api/heroui-agent/auth-token", {
+          method: "POST",
+          headers: {"Content-Type": "application/json"},
+          body: JSON.stringify(context),
+        });
+
+        if (!response.ok) throw new Error("Agent authentication failed");
+
+        return response.json();
+      }}
+    />
+  );
+}
+```
+
+Mint the short-lived browser credential on your server — never expose the project API key to the client:
+
+```ts
+import {createAuthToken} from "@heroui/agent/server";
+
+export async function POST(request: Request) {
+  const {anonymousId, agentId} = await request.json();
+
+  return Response.json(
+    await createAuthToken({
+      apiKey: process.env.HEROUI_AGENT_API_KEY!,
+      identity: {id: anonymousId, type: "anonymous"},
+      agentId,
+    }),
+  );
+}
+```
+
+## Overview
+
+`@heroui/agent` provides a unified SDK for embedding HeroUI Agents into web applications.
+
+### Entrypoints
+
+| Entrypoint                                   | Description                            | Links                                                                                                                   |
+| -------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| [`@heroui/agent`](#herouiagent)              | React embed, hooks, and client tools   | [npm](https://www.npmjs.com/package/@heroui/agent) • [Docs](https://heroui.pro/docs/agent/getting-started/installation) |
+| [`@heroui/agent/next`](#herouiagentnext)     | Next.js App Router entry               | [Docs](https://heroui.pro/docs/agent/getting-started/installation)                                                      |
+| [`@heroui/agent/server`](#herouiagentserver) | Server helpers for minting auth tokens | [Docs](https://heroui.pro/docs/agent/getting-started/identifying-users)                                                 |
+| [`@heroui/agent/css`](#styles)               | Agent stylesheet                       | —                                                                                                                       |
+| [`@heroui/agent/contracts`](#contracts)      | Shared protocol types and schemas      | —                                                                                                                       |
+
+## Package Details
+
+### @heroui/agent
+
+The core React SDK for embedding a hosted agent.
+
+#### Features
+
+- **Generative UI** — Charts, tables, metrics, and forms streamed from a validated component union
+- **Client tools** — Typed browser functions that run with the signed-in user's session
+- **Dashboard-driven appearance** — Theme, launcher, greeting, and composer without a redeploy
+- **Anonymous → identified** — Merge guest history when the user signs in
+- **Edge-safe contracts** — Protocol types with no Node built-ins
+
+#### Installation
+
+```bash
+npm install @heroui/agent@beta
+```
+
+### @heroui/agent/next
+
+Next.js App Router entry that mirrors the root export.
+
+```tsx
+import {HeroUIAgent} from "@heroui/agent/next";
+```
+
+### @heroui/agent/server
+
+Server-only helpers for exchanging a project API key for a short-lived browser credential.
+
+```ts
+import {createAuthToken} from "@heroui/agent/server";
+```
+
+### Styles
+
+```css
+@import "@heroui/agent/css";
+```
+
+Optional Pro theme variants (`brutalism`, `glass`, `mouve`) ship from [`@heroui-pro/react`](https://heroui.pro/docs):
+
+```tsx
+import "@heroui/agent/css";
+import "@heroui-pro/react/agent-themes/glass";
+```
+
+### Contracts
+
+Shared protocol version, message types, and schemas used by the SDK and hosted API.
+
+```ts
+import {HEROUI_AGENT_PROTOCOL_VERSION} from "@heroui/agent/contracts";
+```
+
+## Client Tools
+
+Client tools let the agent call into your application — fetch data, change filters, create records:
+
+```tsx
+import {HeroUIAgent, createToolHelper} from "@heroui/agent";
+import {z} from "zod";
+
+const tool = createToolHelper<{apiClient: ApiClient}>();
+
+const tools = [
+  tool({
+    name: "search_users",
+    description: "Search for users by name or email",
+    parameters: z.object({query: z.string()}),
+    execute: ({query}, context) => context.apiClient.searchUsers(query),
+  }),
+];
+
+<HeroUIAgent agentId="proj_..." getAuthToken={getAuthToken} context={{apiClient}} tools={tools} />;
+```
+
+Only tool names, descriptions, and JSON schemas reach the hosted agent. Implementations and `context` never leave the browser.
+
+[Learn more](https://heroui.pro/docs/agent/api-reference/client-tools)
+
+## Documentation
+
+- [Installation](https://heroui.pro/docs/agent/getting-started/installation)
+- [Identifying users](https://heroui.pro/docs/agent/getting-started/identifying-users)
+- [Configuration](https://heroui.pro/docs/agent/api-reference/configuration)
+- [Client tools](https://heroui.pro/docs/agent/api-reference/client-tools)
+- [Appearance](https://heroui.pro/docs/agent/configure/appearance)
+- [Configure](https://heroui.pro/docs/agent/configure)
+
+Projects and API keys are managed in the [Agents dashboard](https://heroui.pro/dashboard/agents).
+
+## What runs where
+
+The browser sends every message through the HeroUI API, which owns the model,
+the durable run, the conversation store, and server-side tools. Answers stream
+back over a direct read-only realtime connection so tokens and client-tool
+calls arrive without an API proxy hop.
+
+| In the browser                               | Behind the HeroUI API                        |
+| -------------------------------------------- | -------------------------------------------- |
+| Panel, theme, composer, generated UI         | Model orchestration and the durable run      |
+| Client tools, running as the signed-in user  | Server tools, MCP servers, knowledge search  |
+| A short-lived, read-only answer stream token | Runtime credentials and conversation storage |
+
+## Compatibility
+
+- React 19+
+- Next.js 15+ for `@heroui/agent/next`
+- Chrome/Edge 120+, Firefox 121+, Safari 17.2+
+- ESM only
+
+This SDK speaks protocol version `5`. The hosted API returns `426 Upgrade Required` when a beta SDK is no longer compatible.
+
+## Support
+
+- [Documentation](https://heroui.pro/docs/agent)
+- [Agents product](https://www.heroui.com/agents)
+- [Issues](https://github.com/heroui-inc/heroui-platform/issues)
+- [Discord](https://discord.gg/9b6yyZKmH4)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Built by [HeroUI](https://www.heroui.com)