@astralbeam/sdk 0.15.1 → 0.16.0

package/README.md

@@ -8,7 +8,7 @@ npm install @astralbeam/sdk
 
 ## Quick start
 
-One component in React, one function everywhere else. Full setup, including the required token endpoint, is in [Getting started](https://app.astralbeam.ai/docs/sdk/getting-started).
+One component in React, one function everywhere else. Full setup, including the required token endpoint, is in [Getting started](https://astralbeam.ai/docs/sdk/getting-started).
 
 ```tsx
 import { AstralBeamChat } from "@astralbeam/sdk/react"
@@ -25,11 +25,11 @@ const handle = mountAstralBeamChat(document.getElementById("sidebar"), {})
 // Update with handle.update({ colorScheme: "dark" }), then clean up with handle.unmount().
 ```
 
-Without npm or a bundler, import the same entry from jsDelivr in a module script. Pin an exact version and the full `/dist/client.js` path, because the loader imports its lazy chunks relative to itself. See [Script tag](https://app.astralbeam.ai/docs/sdk/script-tag).
+Without npm or a bundler, import the same entry from jsDelivr in a module script. Pin an exact version and the full `/dist/client.js` path, because the loader imports its lazy chunks relative to itself. See [Script tag](https://astralbeam.ai/docs/sdk/script-tag).
 
 ```html
 <script type="module">
-  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/sdk@0.15.1/dist/client.js"
+  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/sdk@0.16.0/dist/client.js"
 
   mountAstralBeamChat(document.getElementById("sidebar"), {})
 </script>
@@ -43,7 +43,7 @@ Without npm or a bundler, import the same entry from jsDelivr in a module script
 
 ## Authentication
 
-Your server must authenticate the host session and mint a chat token before the widget can chat. Keep the API key server-only. See [Authentication](https://app.astralbeam.ai/docs/sdk/authentication).
+Your server must authenticate the host session and mint a chat token before the widget can chat. Keep the API key server-only. See [Authentication](https://astralbeam.ai/docs/sdk/authentication).
 
 ```ts
 import { createAstralBeamToken } from "@astralbeam/sdk/server"
@@ -79,35 +79,43 @@ export async function POST(request: Request) {
 - Authenticate once and derive stable `user.id` and `tenant.id` values from that trusted session.
 - Keep API keys server-only. Tokens are signed, not encrypted, so their claims must contain no secrets.
 - Return `Cache-Control: no-store` and fail closed when configuration or authentication is missing.
-- Directory access additionally requires signed `user.admin: true`, derived from trusted tenant permissions, and persisted records. Follow [Tenant directories](https://app.astralbeam.ai/docs/sdk/listings).
-- For employee-facing Tenant management, use `createAstralBeamOrganizationToken`. The [API client guide](https://app.astralbeam.ai/docs/sdk/api) covers database-backed roles and browser integration.
+- 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://app.astralbeam.ai/docs/sdk/authentication).
+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).
 
 ## Options
 
-Every option is also a prop on `<AstralBeamChat>`. `handle.update(options)` applies any subset in place, and no option is fixed at mount. Details in [Configuration](https://app.astralbeam.ai/docs/sdk/configuration).
+Every option is also a prop on `<AstralBeamChat>`. `handle.update(options)` applies any subset in place, and no option is fixed at mount. Details in [Configuration](https://astralbeam.ai/docs/sdk/configuration).
 
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `agentId` | organization's default | `agent_<orgId>_<id>`, copied from the dashboard |
-| `apiUrl` | `https://app.astralbeam.ai/api` | Base URL of the AstralBeam API. The widget calls `/v1/chat` there |
+| `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's unsent text per thread stays in local storage and never sends automatically. Selected attachments remain in memory. 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://app.astralbeam.ai/docs/sdk/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).
 
 ```tsx
 tools: {
@@ -135,25 +143,25 @@ widgets: {
 
 | Guide | Covers |
 | --- | --- |
-| [API client](https://app.astralbeam.ai/docs/sdk/api) | Typed resource and chat requests with API keys or JWTs. |
-| [Getting started](https://app.astralbeam.ai/docs/sdk/getting-started) | install, mount, layout requirements. |
-| [Script tag](https://app.astralbeam.ai/docs/sdk/script-tag) | loading from jsDelivr without a bundler, and Ruby on Rails. |
-| [Authentication](https://app.astralbeam.ai/docs/sdk/authentication) | the token endpoint, its security rules, and minting in other languages. |
-| [Tenant directories](https://app.astralbeam.ai/docs/sdk/listings) | provisioning, tenant-user and Tenant listings, lifecycle, and options. |
-| [Configuration](https://app.astralbeam.ai/docs/sdk/configuration) | every option, and what `update` can change. |
-| [Theming](https://app.astralbeam.ai/docs/sdk/theming) | color schemes, CSS tokens, the shadow-root boundary. |
-| [Tools and widgets](https://app.astralbeam.ai/docs/sdk/tools-and-widgets) | schemas, live state, rendering into the transcript. |
-| [Attachments](https://app.astralbeam.ai/docs/sdk/attachments) | file kinds, limits, what the endpoint enforces. |
-| [Limits](https://app.astralbeam.ai/docs/sdk/limits) | request, attachment, and sandbox limits. |
-| [Sandbox](https://app.astralbeam.ai/docs/sdk/sandbox) | steps, the opt-in panel, downloads, inline images. |
-| [Headless](https://app.astralbeam.ai/docs/sdk/headless) | own the whole chat UI on the same session. |
-| [Security model](https://app.astralbeam.ai/docs/sdk/security) | who grants, who enforces, what the client can change. |
+| [API client](https://astralbeam.ai/docs/sdk/api) | Typed resource and chat requests with API keys or JWTs. |
+| [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 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. |
+| [Attachments](https://astralbeam.ai/docs/sdk/attachments) | file kinds, limits, what the endpoint enforces. |
+| [Limits](https://astralbeam.ai/docs/sdk/limits) | request, attachment, and sandbox limits. |
+| [Sandbox](https://astralbeam.ai/docs/sdk/sandbox) | steps, the opt-in panel, downloads, inline images. |
+| [Headless](https://astralbeam.ai/docs/sdk/headless) | own the whole chat UI on the same session. |
+| [Security model](https://astralbeam.ai/docs/sdk/security) | who grants, who enforces, what the client can change. |
 
 ## Entry points
 
-Read-only Tenant and TenantUser widgets are available from `/client` and `/react`. See [Tenant directories](https://app.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. Conversations are saved on the server and can be reopened across clients.
 
 | Entry point              | Contents                                     | Peer dependency      |
 | ------------------------ | -------------------------------------------- | -------------------- |