@astralbeam/sdk 0.5.0 → 0.7.0

package/README.md

@@ -28,34 +28,41 @@ const handle = mountAstralBeamChat(document.getElementById("sidebar"), {})
 - The widget fills its container, so give it a parent with a definite height (`min-h-0` in a flex column).
 - Two origins by design: chat streams to the hosted cloud by default, while the token comes from your own app's endpoint. Self-hosted deployments set `apiUrl` to their own origin.
 - `@astralbeam/sdk/client` ships no React; the chat loads as a lazy chunk with its own bundled copy.
-- `react` and `react-dom` are optional peer dependencies used only by `@astralbeam/sdk/react`.
+- No runtime dependencies; `react` and `react-dom` are optional peers used only by `@astralbeam/sdk/react`.
 - Mount it above your router if the transcript should survive page navigation.
 
 ## Authentication
 
-The widget will not chat until your app mints it a short-lived token; it never sees your API key. See [Authentication](https://app.astralbeam.ai/docs/sdk/authentication).
+The widget will not chat until your app mints it a short-lived chat auth token; it never sees your API key. That token is the credential your server signs for AstralBeam, never your app's own session cookie or access token. See [Authentication](https://app.astralbeam.ai/docs/sdk/authentication).
 
 ```ts
-import { createAstralBeamTokenRoute } from "@astralbeam/sdk/server"
-
-export const POST = createAstralBeamTokenRoute({
-  apiKey: () => process.env.ASTRALBEAM_API_KEY, // key_<organization>_<key>_abo_<secret>
-  authenticate: (request) => getApplicationSession(request),
-  user: (session) => ({
-    id: session.user.id,
-    name: session.user.name,
-    metadata: { email: session.user.email },
-  }),
-  tenant: (session) => ({
-    id: session.tenant.id,
-    name: session.tenant.name,
-    metadata: { plan: session.tenant.plan },
-  }),
-})
+import { createChatAuthToken } from "@astralbeam/sdk/server"
+
+const apiKey = process.env.ASTRALBEAM_API_KEY // key_<organization>_<key>_abo_<secret>
+
+export async function POST(request: Request) {
+  if (!apiKey) return Response.json({ error: "Not configured" }, { status: 503 })
+  const session = await getApplicationSession(request)
+  if (!session) return Response.json({ error: "Unauthenticated" }, { status: 401 })
+  const token = await createChatAuthToken({
+    apiKey,
+    user: {
+      id: session.user.id,
+      name: session.user.name,
+      metadata: { email: session.user.email },
+    },
+    tenant: {
+      id: session.tenant.id,
+      name: session.tenant.name,
+      metadata: { plan: session.tenant.plan },
+    },
+  })
+  return Response.json({ token }, { headers: { "cache-control": "no-store" } })
+}
 ```
 
 - Add one endpoint, `/api/astralbeam/token` by default, that authenticates your own session first.
-- The factory owns the method check, the unconfigured 503, the unauthenticated 401, and `no-store`.
+- Your handler owns the response: answer `cache-control: no-store`, and fail closed with a 401 or 503.
 - Authenticate once, then derive `user` and `tenant` separately from that same application session.
 - Derive `user` and `tenant` from trusted server-side state, never from anything the browser sent.
 - Provide stable tenant-local `user.id` and stable `tenant.id` values; names are optional, and set `user.admin` only from trusted state.
@@ -64,7 +71,7 @@ export const POST = createAstralBeamTokenRoute({
 - Tokens use the API key's organization slug as issuer and the platform audience `astralbeam`; AstralBeam does not require or interpret `sub`.
 - Tokens are signed, not encrypted: never put a secret in them.
 - Lifetimes are 60–600 seconds; the SDK renews in memory before expiry.
-- `generateAuthToken` says where the token comes from: `{ url, ...init }`, which the widget calls as `fetch(url, init)` with a standard `RequestInit`, or a function returning `{ token }` (or a promise of it, or `undefined` when it cannot mint one).
+- `fetchChatAuthToken` says where the chat auth token comes from: `{ url, ...init }`, which the widget calls as `fetch(url, init)` with a standard `RequestInit`, or a function returning `{ token }` (or a promise of it, or `undefined` when it cannot mint one).
 - It defaults to `{ url: "/api/astralbeam/token" }`, posted with the page's cookies, and runs again on every renewal, so a rotating credential stays current.
 
 ## Options
@@ -73,9 +80,9 @@ Every option is also a prop on `<AstralBeamChat>`; `handle.update(options)` appl
 
 | Option                               | Default                            | Meaning                                                            |
 | ------------------------------------ | ---------------------------------- | ------------------------------------------------------------------ |
-| `agentId`                            | organization's default             | `agt_<organization>_<agent>` from the dashboard                    |
+| `agentId`                            | organization's default             | `agent_<uuid>`, copied from the dashboard                          |
 | `apiUrl`                             | `https://app.astralbeam.ai/api`    | Base URL of the AstralBeam API; the widget calls `/chat` there     |
-| `generateAuthToken`                  | `{ url: "/api/astralbeam/token" }` | Token endpoint as `{ url, ...RequestInit }`, or a minting function |
+| `fetchChatAuthToken`                 | `{ 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                      |
 | `colorScheme`, `theme`               | `"system"`, built-in palette       | Light/dark/system, and shadcn token overrides                      |
@@ -133,13 +140,12 @@ Each guide is short and self-contained.
 
 There is no root export. Conversation history is not built yet.
 
-| Entry point              | Contents                                                  | Peer dependency      |
-| ------------------------ | --------------------------------------------------------- | -------------------- |
-| `@astralbeam/sdk/client` | `mountAstralBeamChat`, the vanilla loader                 | none                 |
-| `@astralbeam/sdk/core`   | `createAstralBeamChat`, the headless session              | none                 |
-| `@astralbeam/sdk/react`  | `<AstralBeamChat>`, `useAstralBeamChat`                   | `react`, `react-dom` |
-| `@astralbeam/sdk/server` | `createAstralBeamChatToken`, `createAstralBeamTokenRoute` | none                 |
-| `@astralbeam/sdk/vue`    | Vue components (placeholder)                              | `vue`                |
+| Entry point              | Contents                                     | Peer dependency      |
+| ------------------------ | -------------------------------------------- | -------------------- |
+| `@astralbeam/sdk/client` | `mountAstralBeamChat`, the vanilla loader    | none                 |
+| `@astralbeam/sdk/core`   | `createAstralBeamChat`, the headless session | none                 |
+| `@astralbeam/sdk/react`  | `<AstralBeamChat>`, `useAstralBeamChat`      | `react`, `react-dom` |
+| `@astralbeam/sdk/server` | `createChatAuthToken`, the token minter      | none                 |
 
 Types resolve under every TypeScript module resolution mode, including the classic `"moduleResolution": "node"` that Ionic, Capacitor, and Create React App templates still ship. TypeScript 5.0 or later is required, because the declarations use `const` type parameters; on TypeScript 4.x the `.d.ts` files fail to parse.
 

package/dist/client.d.ts

@@ -108,14 +108,14 @@ interface AstralBeamChatAuthTokenRequest extends RequestInit {
   url: string;
 }
 /**
- * Where the widget's short-lived chat JWT comes from: an endpoint to POST, or a function that
+ * Where the widget's short-lived chat auth token comes from: an endpoint to POST, or a function that
  * mints the token in the host page and returns `{ token }`, optionally as a promise.
  *
  * Either form runs again on every renewal — near expiry and after a token is rejected — so a
  * rotating credential stays current rather than being captured once. A function that returns
  * `undefined`, or throws, fails authentication closed; the composer's retry link asks again.
  */
-type AstralBeamChatGenerateAuthToken = AstralBeamChatAuthTokenRequest | (() => {
+type AstralBeamChatAuthTokenSource = AstralBeamChatAuthTokenRequest | (() => {
   token: string;
 } | undefined | Promise<{
   token: string;
@@ -130,6 +130,11 @@ interface AstralBeamChatTheme {
   light?: AstralBeamChatThemeVariables | undefined;
   dark?: AstralBeamChatThemeVariables | undefined;
 }
+/**
+ * Every option of the drop-in chat widget, and the one documented source the React props and the
+ * headless core options are derived from. Each is optional and accepts an explicit `undefined`, so
+ * a host with `exactOptionalPropertyTypes` can pass a value it does not have yet.
+ */
 interface MountAstralBeamChatOptions {
   /**
    * Public ID of the organization-owned agent. Omit it to use the organization's default agent,
@@ -155,16 +160,16 @@ interface MountAstralBeamChatOptions {
    */
   apiUrl?: string | undefined;
   /**
-   * Where the short-lived chat JWT comes from: `{ url, ...RequestInit }` for a token endpoint, or
-   * a function that mints `{ token }` in the host page. Read for every token, so a change applies
-   * to the next one, which is minted when the cached token nears expiry. Default
+   * Where the short-lived chat auth token comes from: `{ url, ...RequestInit }` for a token
+   * endpoint, or a function that mints `{ token }` in the host page. Read for every token, so a
+   * change applies to the next one, which is minted when the cached token nears expiry. Default
    * `{ url: "/api/astralbeam/token" }`, posted with the page's cookies.
    */
-  generateAuthToken?: AstralBeamChatGenerateAuthToken | undefined;
+  fetchChatAuthToken?: AstralBeamChatAuthTokenSource | undefined;
   /** Host-defined tools the agent can call, executed in the host page, keyed by tool name. */
   tools?: Record<string, ToolDefinition> | undefined;
   /** Host-defined widgets the agent can render inline in the conversation, keyed by identifier. */
-  widgets?: Record<string, WidgetDefinition>;
+  widgets?: Record<string, WidgetDefinition> | undefined;
   /** Host-rendered replacements for parts of the widget's chrome; see `AstralBeamChatSlots`. */
   slots?: AstralBeamChatSlots | undefined;
   /**
@@ -179,7 +184,7 @@ interface MountAstralBeamChatOptions {
    */
   attachments?: boolean | AstralBeamChatAttachmentOptions | undefined;
   /** Color scheme of the widget. Default `"system"`. */
-  colorScheme?: AstralBeamChatColorScheme;
+  colorScheme?: AstralBeamChatColorScheme | undefined;
   /** Custom values for the widget's theming CSS variables, per color scheme. */
   theme?: AstralBeamChatTheme | undefined;
   /**
@@ -227,4 +232,4 @@ declare function defineWidget<const S extends ParametersSchema = JsonSchemaObjec
 //#region src/client/index.d.ts
 declare function mountAstralBeamChat(target: HTMLElement, options: MountAstralBeamChatOptions): AstralBeamChatHandle;
 //#endregion
-export { type AstralBeamChatAttachmentOptions, type AstralBeamChatAuthTokenRequest, type AstralBeamChatColorScheme, type AstralBeamChatGenerateAuthToken, type AstralBeamChatHandle, type AstralBeamChatSlotRenderer, type AstralBeamChatSlots, type AstralBeamChatTheme, type AstralBeamChatThemeVariables, type AstralBeamChatUpdate, type InferParameters, type JsonSchemaObject, type MountAstralBeamChatOptions, type ParametersSchema, type StandardSchemaV1, type ToolDefinition, type TypedToolDefinition, type TypedWidgetDefinition, type WidgetDefinition, defineTool, defineWidget, mountAstralBeamChat };
+export { type AstralBeamChatAttachmentOptions, type AstralBeamChatAuthTokenRequest, type AstralBeamChatAuthTokenSource, type AstralBeamChatColorScheme, type AstralBeamChatHandle, type AstralBeamChatSlotRenderer, type AstralBeamChatSlots, type AstralBeamChatTheme, type AstralBeamChatThemeVariables, type AstralBeamChatUpdate, type InferParameters, type JsonSchemaObject, type MountAstralBeamChatOptions, type ParametersSchema, type StandardSchemaV1, type ToolDefinition, type TypedToolDefinition, type TypedWidgetDefinition, type WidgetDefinition, defineTool, defineWidget, mountAstralBeamChat };

package/dist/client.js

@@ -1 +1 @@
-import{c as e,t}from"./debug-DyjRg3e0.js";function n(e){return e}function r(e){return e}function i(n,r){let i={...r},a=t(i.debug);a?.(`mount`,`mounting chat widget`,{agentId:i.agentId??`(organization default)`,title:i.title??`AstralBeam`,showHeader:i.showHeader??!0,emptyTitle:i.emptyTitle??`Ask the assistant`,emptyDescription:i.emptyDescription??`It can answer questions and act through this app's own tools and widgets.`,apiUrl:i.apiUrl??`https://app.astralbeam.ai/api`,authentication:`configured`,colorScheme:i.colorScheme??`system`,theme:i.theme,tools:Object.keys(i.tools??{}),widgets:Object.keys(i.widgets??{}),attachments:i.attachments??!0});let o=n.shadowRoot??n.attachShadow({mode:`open`}),s=document.createElement(`div`);s.className=e,s.style.height=`100%`,o.append(s);let c=matchMedia(`(prefers-color-scheme: dark)`),l=new Set,u=e=>{for(let e of l)s.style.removeProperty(e);l.clear();let t={...i.theme?.light,...e?i.theme?.dark:void 0};for(let[e,n]of Object.entries(t))e.startsWith(`--`)&&(s.style.setProperty(e,n),l.add(e))},d=()=>{let e=i.colorScheme??`system`,t=e===`dark`||e===`system`&&c.matches;s.classList.toggle(`dark`,t),u(t),a?.(`theme`,`color scheme "${e}" resolved to ${t?`dark`:`light`}`,{themeVariables:[...l]})};d(),c.addEventListener(`change`,d);let f=!1,p;return import(`./widget-DiGFLZyX.js`).then(({renderChat:e})=>{a?.(`mount`,`chat chunk loaded`),f||(p=e(o,s,i))}),{update:e=>{i={...i,...e},a=t(i.debug),a?.(`mount`,`options updated`,{changed:Object.keys(e)}),d(),p?.update(i)},reset:()=>p?.reset(),stop:()=>p?.stop(),unmount:()=>{a?.(`mount`,`unmounting chat widget`),f=!0,c.removeEventListener(`change`,d),p?.dispose(),p=void 0,s.remove()}}}export{n as defineTool,r as defineWidget,i as mountAstralBeamChat};
+import{c as e,t}from"./debug-DyjRg3e0.js";function n(e){return e}function r(e){return e}function i(n,r){let i={...r},a=t(i.debug);a?.(`mount`,`mounting chat widget`,{agentId:i.agentId??`(organization default)`,title:i.title??`AstralBeam`,showHeader:i.showHeader??!0,emptyTitle:i.emptyTitle??`Ask the assistant`,emptyDescription:i.emptyDescription??`It can answer questions and act through this app's own tools and widgets.`,apiUrl:i.apiUrl??`https://app.astralbeam.ai/api`,authentication:`configured`,colorScheme:i.colorScheme??`system`,theme:i.theme,tools:Object.keys(i.tools??{}),widgets:Object.keys(i.widgets??{}),attachments:i.attachments??!0});let o=n.shadowRoot??n.attachShadow({mode:`open`}),s=document.createElement(`div`);s.className=e,s.style.height=`100%`,o.append(s);let c=matchMedia(`(prefers-color-scheme: dark)`),l=new Set,u=e=>{for(let e of l)s.style.removeProperty(e);l.clear();let t={...i.theme?.light,...e?i.theme?.dark:void 0};for(let[e,n]of Object.entries(t))e.startsWith(`--`)&&(s.style.setProperty(e,n),l.add(e))},d=()=>{let e=i.colorScheme??`system`,t=e===`dark`||e===`system`&&c.matches;s.classList.toggle(`dark`,t),u(t),a?.(`theme`,`color scheme "${e}" resolved to ${t?`dark`:`light`}`,{themeVariables:[...l]})};d(),c.addEventListener(`change`,d);let f=!1,p;return import(`./widget-PZ-6BF36.js`).then(({renderChat:e})=>{a?.(`mount`,`chat chunk loaded`),f||(p=e(o,s,i))}),{update:e=>{i={...i,...e},a=t(i.debug),a?.(`mount`,`options updated`,{changed:Object.keys(e)}),d(),p?.update(i)},reset:()=>p?.reset(),stop:()=>p?.stop(),unmount:()=>{a?.(`mount`,`unmounting chat widget`),f=!0,c.removeEventListener(`change`,d),p?.dispose(),p=void 0,s.remove()}}}export{n as defineTool,r as defineWidget,i as mountAstralBeamChat};

package/dist/{core-BZxnUlwg.js → core-BF1G1dLe.js}

@@ -7842,29 +7842,29 @@ function buildHostTools(tools, debug) {
 const REFRESH_SKEW_MS = 6e4;
 const MAX_TOKEN_LENGTH = 16384;
 function tokenExpiry(token) {
-	if (token.length > MAX_TOKEN_LENGTH) throw new Error("The authentication token is too large");
+	if (token.length > MAX_TOKEN_LENGTH) throw new Error("The chat auth token is too large");
 	const parts = token.split(".");
-	if (parts.length !== 3 || !parts[1]) throw new Error("The authentication token is not a JWT");
+	if (parts.length !== 3 || !parts[1]) throw new Error("The chat auth token is not a JWT");
 	const encoded = parts[1].replaceAll("-", "+").replaceAll("_", "/");
 	const padded = encoded.padEnd(Math.ceil(encoded.length / 4) * 4, "=");
 	let payload;
 	try {
 		payload = JSON.parse(atob(padded));
 	} catch {
-		throw new Error("The authentication token has an invalid payload");
+		throw new Error("The chat auth token has an invalid payload");
 	}
 	const exp = payload?.exp;
-	if (!Number.isInteger(exp) || Number(exp) <= 0) throw new Error("The authentication token has no valid expiry");
+	if (!Number.isInteger(exp) || Number(exp) <= 0) throw new Error("The chat auth token has no valid expiry");
 	return Number(exp) * 1e3;
 }
 function bearerToken(headers) {
 	const authorization = headers.get("authorization");
 	return authorization?.startsWith("Bearer ") ? authorization.slice(7) : void 0;
 }
-async function requestChatToken(options, signal) {
-	const { generateAuthToken, fetchClient } = options;
-	if (typeof generateAuthToken === "function") return (await generateAuthToken())?.token;
-	const { url, ...init } = generateAuthToken;
+async function requestChatAuthToken(options, signal) {
+	const { fetchChatAuthToken, fetchClient } = options;
+	if (typeof fetchChatAuthToken === "function") return (await fetchChatAuthToken())?.token;
+	const { url, ...init } = fetchChatAuthToken;
 	const headers = new Headers(init.headers);
 	if (!headers.has("accept")) headers.set("accept", "application/json");
 	const response = await fetchClient(url, {
@@ -7878,12 +7878,12 @@ async function requestChatToken(options, signal) {
 	if (!response.ok) throw new Error(`Authentication endpoint returned HTTP ${response.status}`);
 	return (await response.json())?.token;
 }
-async function fetchChatToken(options) {
+async function loadChatAuthToken(options) {
 	const { session, onStateChange, debug } = options;
 	const { signal } = session.abortController;
-	const source = typeof options.generateAuthToken === "function" ? "generateAuthToken" : "Authentication endpoint";
+	const source = typeof options.fetchChatAuthToken === "function" ? "fetchChatAuthToken" : "Authentication endpoint";
 	try {
-		const token = await requestChatToken(options, signal);
+		const token = await requestChatAuthToken(options, signal);
 		if (typeof token !== "string" || !token) throw new Error(`${source} did not return a token`);
 		const expiresAt = tokenExpiry(token);
 		if (expiresAt <= Date.now()) throw new Error(`${source} returned an expired token`);
@@ -7906,13 +7906,13 @@ async function fetchChatToken(options) {
 		throw error;
 	}
 }
-async function getValidChatToken(options) {
+async function getValidChatAuthToken(options) {
 	const { session, force = false, onStateChange } = options;
 	const now = Date.now();
 	if (!force && session.cached && session.cached.expiresAt - now > REFRESH_SKEW_MS) return session.cached.value;
 	if (session.refreshPromise) return await session.refreshPromise;
 	onStateChange({ status: "loading" });
-	const refresh = fetchChatToken(options);
+	const refresh = loadChatAuthToken(options);
 	session.refreshPromise = refresh;
 	try {
 		return await refresh;
@@ -7922,7 +7922,7 @@ async function getValidChatToken(options) {
 }
 async function initializeChatAuthentication(options) {
 	if (options.session.abortController.signal.aborted) options.session.abortController = new AbortController();
-	await getValidChatToken(options);
+	await getValidChatAuthToken(options);
 }
 function disposeChatAuthentication({ session }) {
 	session.abortController.abort();
@@ -7935,8 +7935,8 @@ async function fetchAuthenticatedChat(options) {
 	const usedToken = bearerToken(new Headers(init?.headers));
 	const rejectedCurrentToken = !usedToken || session.cached?.value === usedToken;
 	if (rejectedCurrentToken) session.cached = void 0;
-	debug?.("auth", "chat token was rejected; refreshing once");
-	const token = await getValidChatToken({
+	debug?.("auth", "chat auth token was rejected; refreshing once");
+	const token = await getValidChatAuthToken({
 		...options,
 		force: rejectedCurrentToken
 	});
@@ -8076,6 +8076,19 @@ function describeSandboxCommandRun(run) {
 }
 //#endregion
 //#region src/core/session.ts
+const CORE_OPTION_KEYS = Object.keys({
+	agentId: true,
+	apiUrl: true,
+	fetchChatAuthToken: true,
+	tools: true,
+	widgets: true,
+	onRenderWidget: true,
+	streamCallbacks: true,
+	debug: true
+});
+function sameAgentTools(current, next) {
+	return current.length === next.length && current.every((tool, index) => tool.name === next[index]?.name && tool.title === next[index]?.title);
+}
 /**
 * The headless AstralBeam chat session: authentication, transport, the tool protocol, and
 * transcript state, with no markup. The drop-in widget is one consumer; a host that owns its
@@ -8091,6 +8104,7 @@ function createAstralBeamChat(options) {
 		error: void 0,
 		auth: { status: "loading" },
 		capabilities: { attachments: true },
+		agentTools: [],
 		sandboxStatus: void 0,
 		sandbox: {
 			files: [],
@@ -8105,7 +8119,7 @@ function createAstralBeamChat(options) {
 		for (const listener of listeners) listener();
 	};
 	const authentication = {
-		generateAuthToken: live.generateAuthToken ?? { url: "/api/astralbeam/token" },
+		fetchChatAuthToken: live.fetchChatAuthToken ?? { url: "/api/astralbeam/token" },
 		session: {
 			cached: void 0,
 			refreshPromise: void 0,
@@ -8116,15 +8130,20 @@ function createAstralBeamChat(options) {
 		debug
 	};
 	initializeChatAuthentication(authentication).catch(() => void 0);
+	let capabilitiesGeneration = 0;
 	const resolveCapabilities = async () => {
+		const generation = ++capabilitiesGeneration;
 		try {
 			const url = new URL(chatApiUrls(live.apiUrl).config, globalThis.location?.href);
 			if (live.agentId) url.searchParams.set("agentId", live.agentId);
-			const token = await getValidChatToken(authentication);
+			const token = await getValidChatAuthToken(authentication);
 			const response = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
 			if (!response.ok) throw new Error(`The config request answered ${response.status}`);
 			const body = await response.json();
-			update({ capabilities: { attachments: body.capabilities?.attachments !== false } });
+			if (generation !== capabilitiesGeneration) return;
+			const attachments = body.capabilities?.attachments !== false;
+			update({ capabilities: { attachments } });
+			debug?.("mount", "agent capabilities resolved", { attachments });
 		} catch (error) {
 			debug?.("error", "agent capabilities could not be resolved; keeping the defaults", error);
 		}
@@ -8143,32 +8162,52 @@ function createAstralBeamChat(options) {
 		if (validated == null) throw new Error(`Props for widget "${input.widget}" failed validation`);
 		renderCleanups.get(toolCallId)?.();
 		renderCleanups.delete(toolCallId);
+		let registered;
+		const release = () => {
+			if (renderCleanups.get(toolCallId) === registered) renderCleanups.delete(toolCallId);
+		};
 		const cleanup = live.onRenderWidget?.({
 			widget: input.widget,
 			props: validated,
-			toolCallId
+			toolCallId,
+			release
 		});
-		if (cleanup) renderCleanups.set(toolCallId, cleanup);
+		if (cleanup) {
+			registered = cleanup;
+			renderCleanups.set(toolCallId, cleanup);
+		}
 		return {
 			widget: input.widget,
 			rendered: live.onRenderWidget !== void 0
 		};
 	};
-	const agentTools = () => buildAgentTools(live.widgets ?? {}, live.tools ?? {}, renderWidget, debug);
+	const buildTools = () => buildAgentTools(live.widgets ?? {}, live.tools ?? {}, renderWidget, debug);
+	const declareTools = () => {
+		const tools = buildTools();
+		const agentTools = tools.map((tool) => {
+			const title = tool.metadata?.["title"];
+			return {
+				name: tool.name,
+				title: typeof title === "string" && title.length > 0 ? title : void 0
+			};
+		});
+		if (!sameAgentTools(state.agentTools, agentTools)) update({ agentTools });
+		return tools;
+	};
 	const forwardedProps = () => ({
 		...live.agentId ? { agentId: live.agentId } : {},
 		...live.debug ? { debug: true } : {}
 	});
 	const client = new ChatClient({
 		connection: fetchServerSentEvents(() => chatApiUrls(live.apiUrl).chat, async () => ({
-			headers: { authorization: `Bearer ${await getValidChatToken(authentication)}` },
+			headers: { authorization: `Bearer ${await getValidChatAuthToken(authentication)}` },
 			fetchClient: (input, init) => fetchAuthenticatedChat({
 				...authentication,
 				input,
 				init
 			})
 		})),
-		tools: agentTools(),
+		tools: declareTools(),
 		forwardedProps: forwardedProps(),
 		onMessagesChange: (messages) => {
 			update({
@@ -8184,30 +8223,40 @@ function createAstralBeamChat(options) {
 		onCustomEvent: (eventType, data) => {
 			const value = data?.state;
 			if (eventType === "astralbeam.sandbox.status" && (value === "starting" || value === "ready" || value === "error")) {
+				debug?.("sandbox", `sandbox ${value}`);
 				update({ sandboxStatus: value });
 				return;
 			}
 			debug?.("stream", `custom event "${eventType}"`, data);
-		}
+		},
+		onChunk: (chunk) => live.streamCallbacks?.onChunk?.(chunk),
+		onResponse: (response) => live.streamCallbacks?.onResponse?.(response),
+		onFinish: (message) => live.streamCallbacks?.onFinish?.(message),
+		onError: (error) => live.streamCallbacks?.onError?.(error)
 	});
 	const settleDanglingToolCalls = () => {
 		for (const message of state.messages) for (const part of message.parts) {
 			if (part.type !== "tool-call" || isSettledToolCall(part)) continue;
-			if (part.name === "ask_questionnaire") client.addToolResult({
-				toolCallId: part.id,
-				tool: part.name,
-				output: {
-					answers: [],
-					skipped: true
-				}
-			});
-			else client.addToolResult({
-				toolCallId: part.id,
-				tool: part.name,
-				output: null,
-				state: "output-error",
-				errorText: `The application hosting this chat has no implementation for "${part.name}"`
-			});
+			if (part.name === "ask_questionnaire") {
+				debug?.("questionnaire", "skipping pending questionnaire before send", { id: part.id });
+				client.addToolResult({
+					toolCallId: part.id,
+					tool: part.name,
+					output: {
+						answers: [],
+						skipped: true
+					}
+				});
+			} else {
+				debug?.("tool", `settling unimplemented tool call "${part.name}" as error`, { id: part.id });
+				client.addToolResult({
+					toolCallId: part.id,
+					tool: part.name,
+					output: null,
+					state: "output-error",
+					errorText: `The application hosting this chat has no implementation for "${part.name}"`
+				});
+			}
 		}
 	};
 	return {
@@ -8224,10 +8273,10 @@ function createAstralBeamChat(options) {
 				...next
 			};
 			debug = createDebugLogger(live.debug);
-			authentication.generateAuthToken = live.generateAuthToken ?? { url: "/api/astralbeam/token" };
+			authentication.fetchChatAuthToken = live.fetchChatAuthToken ?? { url: "/api/astralbeam/token" };
 			authentication.debug = debug;
 			client.updateOptions({
-				tools: agentTools(),
+				tools: declareTools(),
 				forwardedProps: forwardedProps()
 			});
 			if (live.agentId !== agent || live.apiUrl !== apiUrl) resolveCapabilities();
@@ -8238,8 +8287,15 @@ function createAstralBeamChat(options) {
 		},
 		addToolResult: (result) => client.addToolResult(result),
 		stop: () => client.stop(),
+		retryAuthentication: () => {
+			getValidChatAuthToken({
+				...authentication,
+				force: true
+			}).catch(() => void 0);
+		},
 		reload: () => client.reload(),
 		reset: () => {
+			debug?.("status", "conversation reset");
 			client.clear();
 			disposeRenders();
 			update({
@@ -8266,9 +8322,5 @@ function createAstralBeamChat(options) {
 function defineTool(tool) {
 	return tool;
 }
-/** Declares a host widget; a Standard Schema `parameters` types (and validates) `render`'s props. */
-function defineWidget(widget) {
-	return widget;
-}
 //#endregion
-export { DEFAULT_COLOR_SCHEME as C, SANDBOX_WRITE_FILE_TOOL as S, SANDBOX_LIST_FILES_TOOL as _, describeSandboxCommandRun as a, SANDBOX_RUN_COMMAND_TOOL as b, readSandboxCommandRun as c, hasPendingToolRun as d, isSettledToolCall as f, RENDER_WIDGET_TOOL as g, ASK_QUESTIONNAIRE_TOOL as h, collectSandboxActivity as i, readSandboxFileWrite as l, buildAgentTools as m, defineWidget as n, isSandboxTool as o, lastPartInProgress as p, createAstralBeamChat as r, readSandboxArtifact as s, defineTool as t, sandboxRefusal as u, SANDBOX_PUBLISH_ARTIFACT_TOOL as v, SANDBOX_STATUS_EVENT as x, SANDBOX_READ_FILE_TOOL as y };
+export { DEFAULT_COLOR_SCHEME as C, SANDBOX_WRITE_FILE_TOOL as S, SANDBOX_LIST_FILES_TOOL as _, describeSandboxCommandRun as a, SANDBOX_RUN_COMMAND_TOOL as b, readSandboxCommandRun as c, hasPendingToolRun as d, isSettledToolCall as f, RENDER_WIDGET_TOOL as g, ASK_QUESTIONNAIRE_TOOL as h, collectSandboxActivity as i, readSandboxFileWrite as l, buildAgentTools as m, CORE_OPTION_KEYS as n, isSandboxTool as o, lastPartInProgress as p, createAstralBeamChat as r, readSandboxArtifact as s, defineTool as t, sandboxRefusal as u, SANDBOX_PUBLISH_ARTIFACT_TOOL as v, SANDBOX_STATUS_EVENT as x, SANDBOX_READ_FILE_TOOL as y };

package/dist/core.d.ts

@@ -1,2 +1,2 @@
-import { A as SandboxActivity, C as AstralBeamChatState, D as WidgetDeclaration, E as ChatAuthenticationState, F as InferParameters, I as JsonSchemaObject, L as ParametersSchema, M as SandboxCommandRun, N as SandboxFileWrite, O as buildAgentTools, P as SandboxStatus, R as StandardSchemaV1, S as AstralBeamChatCoreOptions, T as createAstralBeamChat, _ as sandboxRefusal, a as SANDBOX_LIST_FILES_TOOL, b as lastPartInProgress, c as SANDBOX_RUN_COMMAND_TOOL, d as collectSandboxActivity, f as describeSandboxCommandRun, g as readSandboxFileWrite, h as readSandboxCommandRun, i as RENDER_WIDGET_TOOL, j as SandboxArtifact, k as RenderWidgetInput, l as SANDBOX_STATUS_EVENT, m as readSandboxArtifact, n as defineWidget, o as SANDBOX_PUBLISH_ARTIFACT_TOOL, p as isSandboxTool, r as ASK_QUESTIONNAIRE_TOOL, s as SANDBOX_READ_FILE_TOOL, t as defineTool, u as SANDBOX_WRITE_FILE_TOOL, v as hasPendingToolRun, w as WidgetRenderRequest, x as AstralBeamChatCore, y as isSettledToolCall, z as ToolDefinition } from "./index-8NUgB59m.js";
-export { ASK_QUESTIONNAIRE_TOOL, type AstralBeamChatCore, type AstralBeamChatCoreOptions, type AstralBeamChatState, type ChatAuthenticationState, type InferParameters, type JsonSchemaObject, type ParametersSchema, RENDER_WIDGET_TOOL, type RenderWidgetInput, SANDBOX_LIST_FILES_TOOL, SANDBOX_PUBLISH_ARTIFACT_TOOL, SANDBOX_READ_FILE_TOOL, SANDBOX_RUN_COMMAND_TOOL, SANDBOX_STATUS_EVENT, SANDBOX_WRITE_FILE_TOOL, type SandboxActivity, type SandboxArtifact, type SandboxCommandRun, type SandboxFileWrite, type SandboxStatus, type StandardSchemaV1, type ToolDefinition, type WidgetDeclaration, type WidgetRenderRequest, buildAgentTools, collectSandboxActivity, createAstralBeamChat, defineTool, defineWidget, describeSandboxCommandRun, hasPendingToolRun, isSandboxTool, isSettledToolCall, lastPartInProgress, readSandboxArtifact, readSandboxCommandRun, readSandboxFileWrite, sandboxRefusal };
+import { A as RenderWidgetInput, B as ToolDefinition, C as AstralBeamChatState, D as ChatAuthenticationState, E as createAstralBeamChat, F as SandboxStatus, I as InferParameters, L as JsonSchemaObject, M as SandboxArtifact, N as SandboxCommandRun, O as WidgetDeclaration, P as SandboxFileWrite, R as ParametersSchema, S as AstralBeamChatCoreOptions, T as WidgetRenderRequest, _ as hasPendingToolRun, a as SANDBOX_PUBLISH_ARTIFACT_TOOL, b as AgentToolInfo, c as SANDBOX_STATUS_EVENT, d as describeSandboxCommandRun, f as isSandboxTool, g as sandboxRefusal, h as readSandboxFileWrite, i as SANDBOX_LIST_FILES_TOOL, j as SandboxActivity, k as buildAgentTools, l as SANDBOX_WRITE_FILE_TOOL, m as readSandboxCommandRun, n as ASK_QUESTIONNAIRE_TOOL, o as SANDBOX_READ_FILE_TOOL, p as readSandboxArtifact, r as RENDER_WIDGET_TOOL, s as SANDBOX_RUN_COMMAND_TOOL, t as defineTool, u as collectSandboxActivity, v as isSettledToolCall, w as ChatStreamCallbacks, x as AstralBeamChatCore, y as lastPartInProgress, z as StandardSchemaV1 } from "./index-CudekMKM.js";
+export { ASK_QUESTIONNAIRE_TOOL, type AgentToolInfo, type AstralBeamChatCore, type AstralBeamChatCoreOptions, type AstralBeamChatState, type ChatAuthenticationState, type ChatStreamCallbacks, type InferParameters, type JsonSchemaObject, type ParametersSchema, RENDER_WIDGET_TOOL, type RenderWidgetInput, SANDBOX_LIST_FILES_TOOL, SANDBOX_PUBLISH_ARTIFACT_TOOL, SANDBOX_READ_FILE_TOOL, SANDBOX_RUN_COMMAND_TOOL, SANDBOX_STATUS_EVENT, SANDBOX_WRITE_FILE_TOOL, type SandboxActivity, type SandboxArtifact, type SandboxCommandRun, type SandboxFileWrite, type SandboxStatus, type StandardSchemaV1, type ToolDefinition, type WidgetDeclaration, type WidgetRenderRequest, buildAgentTools, collectSandboxActivity, createAstralBeamChat, defineTool, describeSandboxCommandRun, hasPendingToolRun, isSandboxTool, isSettledToolCall, lastPartInProgress, readSandboxArtifact, readSandboxCommandRun, readSandboxFileWrite, sandboxRefusal };

package/dist/core.js

@@ -1,2 +1,2 @@
-import { S as SANDBOX_WRITE_FILE_TOOL, _ as SANDBOX_LIST_FILES_TOOL, a as describeSandboxCommandRun, b as SANDBOX_RUN_COMMAND_TOOL, c as readSandboxCommandRun, d as hasPendingToolRun, f as isSettledToolCall, g as RENDER_WIDGET_TOOL, h as ASK_QUESTIONNAIRE_TOOL, i as collectSandboxActivity, l as readSandboxFileWrite, m as buildAgentTools, n as defineWidget, o as isSandboxTool, p as lastPartInProgress, r as createAstralBeamChat, s as readSandboxArtifact, t as defineTool, u as sandboxRefusal, v as SANDBOX_PUBLISH_ARTIFACT_TOOL, x as SANDBOX_STATUS_EVENT, y as SANDBOX_READ_FILE_TOOL } from "./core-BZxnUlwg.js";
-export { ASK_QUESTIONNAIRE_TOOL, RENDER_WIDGET_TOOL, SANDBOX_LIST_FILES_TOOL, SANDBOX_PUBLISH_ARTIFACT_TOOL, SANDBOX_READ_FILE_TOOL, SANDBOX_RUN_COMMAND_TOOL, SANDBOX_STATUS_EVENT, SANDBOX_WRITE_FILE_TOOL, buildAgentTools, collectSandboxActivity, createAstralBeamChat, defineTool, defineWidget, describeSandboxCommandRun, hasPendingToolRun, isSandboxTool, isSettledToolCall, lastPartInProgress, readSandboxArtifact, readSandboxCommandRun, readSandboxFileWrite, sandboxRefusal };
+import { S as SANDBOX_WRITE_FILE_TOOL, _ as SANDBOX_LIST_FILES_TOOL, a as describeSandboxCommandRun, b as SANDBOX_RUN_COMMAND_TOOL, c as readSandboxCommandRun, d as hasPendingToolRun, f as isSettledToolCall, g as RENDER_WIDGET_TOOL, h as ASK_QUESTIONNAIRE_TOOL, i as collectSandboxActivity, l as readSandboxFileWrite, m as buildAgentTools, o as isSandboxTool, p as lastPartInProgress, r as createAstralBeamChat, s as readSandboxArtifact, t as defineTool, u as sandboxRefusal, v as SANDBOX_PUBLISH_ARTIFACT_TOOL, x as SANDBOX_STATUS_EVENT, y as SANDBOX_READ_FILE_TOOL } from "./core-BF1G1dLe.js";
+export { ASK_QUESTIONNAIRE_TOOL, RENDER_WIDGET_TOOL, SANDBOX_LIST_FILES_TOOL, SANDBOX_PUBLISH_ARTIFACT_TOOL, SANDBOX_READ_FILE_TOOL, SANDBOX_RUN_COMMAND_TOOL, SANDBOX_STATUS_EVENT, SANDBOX_WRITE_FILE_TOOL, buildAgentTools, collectSandboxActivity, createAstralBeamChat, defineTool, describeSandboxCommandRun, hasPendingToolRun, isSandboxTool, isSettledToolCall, lastPartInProgress, readSandboxArtifact, readSandboxCommandRun, readSandboxFileWrite, sandboxRefusal };