@astralbeam/sdk 0.15.2 → 0.17.0

package/README.md

@@ -29,7 +29,7 @@ Without npm or a bundler, import the same entry from jsDelivr in a module script
 
 ```html
 <script type="module">
-  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/sdk@0.15.2/dist/client.js"
+  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/sdk@0.17.0/dist/client.js"
 
   mountAstralBeamChat(document.getElementById("sidebar"), {})
 </script>
@@ -82,7 +82,7 @@ export async function POST(request: Request) {
 - Directory access additionally requires signed `user.admin: true`, derived from trusted tenant permissions, and persisted records. Follow [Tenant directories](https://astralbeam.ai/docs/sdk/listings).
 - For employee-facing Tenant management, use `createAstralBeamOrganizationToken`. The [API client guide](https://astralbeam.ai/docs/sdk/api) covers database-backed roles and browser integration.
 
-Existing token props and the default chat endpoint keep working. After acquiring a token, components call `POST /api/v1/me` and renew before expiry. See [authentication and refresh behavior](https://astralbeam.ai/docs/sdk/authentication).
+After acquiring a token, components call `POST /api/v1/me` and renew before expiry. See [authentication and refresh behavior](https://astralbeam.ai/docs/sdk/authentication).
 
 ## Options
 
@@ -91,20 +91,28 @@ Every option is also a prop on `<AstralBeamChat>`. `handle.update(options)` appl
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `agentId` | organization's default | `agent_<orgId>_<id>`, copied from the dashboard |
+| `threadId` | `"auto"` | Restore this tab's selection, use `"new"` for a fresh chat, or pass a saved thread UUID |
 | `apiUrl` | `https://astralbeam.ai/api` | Base URL of the AstralBeam API. The widget calls `/v1/chat` there |
 | `fetchAstralBeamToken` | `{ url: "/api/astralbeam/token" }` | Chat auth token endpoint as `{ url, ...RequestInit }`, or a minter |
-| `title`, `showHeader` | `"AstralBeam"`, `true` | Header text, and whether the header and reset button show |
-| `emptyTitle`, `emptyDescription` | generic copy | Headline and subtitle of the empty transcript |
+| `title`, `showHeader` | `"AstralBeam"`, `true` | Header text, and whether the header with its chat history and new chat buttons shows |
+| `showConversationTitle` | `false` | Bar with a titled conversation's title and a rename, delete, and Copy Markdown menu |
+| `emptyHeadline`, `emptyDescription` | generic copy | Headline and subtitle of the empty transcript |
 | `colorScheme`, `theme` | `"system"`, built-in palette | Light/dark/system, and shadcn token overrides |
 | `customCss` | None | Trusted CSS inside the widget's Shadow DOM |
 | `attachments` | `true` | `false` hides the feature, or pass limits |
 | `tools`, `widgets` | none | What the agent can do and draw in your app |
 | `sandboxPanel` | `false` | Collected sandbox panel: files with downloads, command log |
-| `header`, `empty`, `composerActions` | widget's own chrome | Host-rendered replacements (React props. `slots` on the handle) |
+| `header`, `headerActions`, `empty`, `composerActions` | widget's own chrome | Host-rendered replacements (React props. `slots` on the handle) |
 | `debug` | `false` | Log SDK actions in the browser, with server logs in development only |
 
 A `ref` on `<AstralBeamChat>` (and the vanilla handle) exposes `reset()` and `stop()` for hosts that draw their own controls.
 
+Conversations are saved automatically and start private. The widget searches saved conversation titles. Reopening history does not execute earlier tool calls. Disconnecting can interrupt the current response.
+
+The headless session exposes conversation navigation, search, and pagination. With `useAstralBeamChat`, access these through `chat.core`, for example `chat.core.openThread(threadId)`. History loads a page at a time. `reset()` starts a new chat and keeps the saved one.
+
+By default, `threadId: "auto"` restores this tab's selection after reload using session storage, scoped to the current account and API. A fresh, independently opened tab starts a new chat. Use `threadId: "new"` to bypass restoration, or pass a saved thread UUID. The widget keeps unsent text and uploaded file references in local storage per account, API, and conversation. Reopening restores the draft without sending it automatically. The host owns sidebar visibility and can persist it separately in session storage.
+
 ## Tools and widgets
 
 A tool does something: its `execute` runs in your page. A widget shows something: its `render` draws your UI into the conversation. Both are declared with a `description` and a `parameters` schema. See [Tools and widgets](https://astralbeam.ai/docs/sdk/tools-and-widgets).
@@ -139,7 +147,7 @@ widgets: {
 | [Getting started](https://astralbeam.ai/docs/sdk/getting-started) | install, mount, layout requirements. |
 | [Script tag](https://astralbeam.ai/docs/sdk/script-tag) | loading from jsDelivr without a bundler, and Ruby on Rails. |
 | [Authentication](https://astralbeam.ai/docs/sdk/authentication) | the token endpoint, its security rules, and minting in other languages. |
-| [Tenant directories](https://astralbeam.ai/docs/sdk/listings) | provisioning, tenant-user and Tenant listings, lifecycle, and options. |
+| [Tenant directories](https://astralbeam.ai/docs/sdk/listings) | provisioning, Tenant and user listings, saved conversation browsing, lifecycle, and options. |
 | [Configuration](https://astralbeam.ai/docs/sdk/configuration) | every option, and what `update` can change. |
 | [Theming](https://astralbeam.ai/docs/sdk/theming) | color schemes, CSS tokens, the shadow-root boundary. |
 | [Tools and widgets](https://astralbeam.ai/docs/sdk/tools-and-widgets) | schemas, live state, rendering into the transcript. |
@@ -151,9 +159,9 @@ widgets: {
 
 ## Entry points
 
-Read-only Tenant and TenantUser widgets are available from `/client` and `/react`. See [Tenant directories](https://astralbeam.ai/docs/sdk/listings) for setup and embedding examples.
+Read-only Tenant, TenantUser and conversation widgets are available from `/client` and `/react`. See [Tenant directories](https://astralbeam.ai/docs/sdk/listings) for setup and embedding examples.
 
-There is no root export. Conversation history is not built yet.
+There is no root export.
 
 | Entry point              | Contents                                     | Peer dependency      |
 | ------------------------ | -------------------------------------------- | -------------------- |