@astralbeam/sdk 0.6.0 → 0.7.0

package/README.md

@@ -28,7 +28,7 @@ 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
@@ -80,7 +80,7 @@ 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     |
 | `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          |
@@ -146,7 +146,6 @@ There is no root export. Conversation history is not built yet.
 | `@astralbeam/sdk/core`   | `createAstralBeamChat`, the headless session | none                 |
 | `@astralbeam/sdk/react`  | `<AstralBeamChat>`, `useAstralBeamChat`      | `react`, `react-dom` |
 | `@astralbeam/sdk/server` | `createChatAuthToken`, the token minter      | none                 |
-| `@astralbeam/sdk/vue`    | Vue components (placeholder)                 | `vue`                |
 
 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

@@ -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,
@@ -164,7 +169,7 @@ interface MountAstralBeamChatOptions {
   /** 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;
   /**

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-CfLWAtV7.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-DYXxodYg.js → core-BF1G1dLe.js}

@@ -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: [],
@@ -8116,7 +8130,9 @@ 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);
@@ -8124,7 +8140,10 @@ function createAstralBeamChat(options) {
 			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,18 +8162,38 @@ 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 } : {}
@@ -8168,7 +8207,7 @@ function createAstralBeamChat(options) {
 				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 {
@@ -8227,7 +8276,7 @@ function createAstralBeamChat(options) {
 			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-TbZxlv54.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-DYXxodYg.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 };

package/dist/{index-TbZxlv54.d.ts → index-CudekMKM.d.ts}

@@ -3305,6 +3305,47 @@ interface ToolDefinition {
    */
   execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
 }
+/**
+ * Limits and accepted types for the composer's file attachments. Every field is optional;
+ * omitting the whole option leaves attachments enabled with the defaults below.
+ */
+interface AstralBeamChatAttachmentOptions {
+  /** Hides the attach button (and ignores drops and pastes) when `false`. Default `true`. */
+  enabled?: boolean | undefined;
+  /** How many files one message may carry. Default `5`. */
+  maxFiles?: number | undefined;
+  /**
+   * Ceiling for a single file, in bytes. The widget also applies its own per-kind caps
+   * (5 MB image, 10 MB PDF, 1 MB text file), so the smaller of the two wins.
+   */
+  maxFileBytes?: number | undefined;
+  /** Ceiling for all files on one message, in bytes. Default 20 MB. */
+  maxTotalBytes?: number | undefined;
+  /**
+   * Narrows what the composer takes, as MIME types or `type/*` patterns (`["image/*"]` for
+   * images only). Omit to accept everything the chat endpoint supports: PNG, JPEG, WebP and
+   * GIF images, PDFs, and text files (which the endpoint reads as text for the agent).
+   */
+  accept?: readonly string[] | undefined;
+}
+/**
+ * Draws host content into `container`, a light-DOM element the widget projects into the
+ * named area. May return a cleanup, called when the slot is replaced and on unmount.
+ */
+type AstralBeamChatSlotRenderer = (container: HTMLElement) => (() => void) | void;
+/** Host-rendered replacements for the widget's own chrome; each renders in the host page's style. */
+interface AstralBeamChatSlots {
+  /** Replaces the header's content (title and reset button); `showHeader: false` still hides the row. */
+  header?: AstralBeamChatSlotRenderer | undefined;
+  /** Replaces the empty-transcript state (icon, headline, and subtitle). */
+  empty?: AstralBeamChatSlotRenderer | undefined;
+  /** Extra controls at the end of the composer's button row, next to send. */
+  composerActions?: AstralBeamChatSlotRenderer | undefined;
+}
+/** Color scheme of the chat widget; `"system"` follows the OS `prefers-color-scheme` setting. */
+type AstralBeamChatColorScheme = "light" | "dark" | "system";
+/** Overrides for the widget's theming CSS variables, keyed by custom-property name (`"--primary"`). */
+type AstralBeamChatThemeVariables = Record<`--${string}`, string>;
 /**
  * A token endpoint to call: `{ url, ...init }`, which the widget calls as `fetch(url, init)` with
  * this object's remaining, standard `RequestInit` fields. The init defaults to `POST`,
@@ -3327,6 +3368,79 @@ type AstralBeamChatAuthTokenSource = AstralBeamChatAuthTokenRequest | (() => {
 } | undefined | Promise<{
   token: string;
 } | undefined>);
+/**
+ * Custom values for the CSS variables the widget's shadcn theme exposes (`--background`,
+ * `--primary`, `--radius`, and the `--font-sans`/`--font-heading`/`--font-mono` stacks, ...),
+ * mirroring shadcn's `:root`/`.dark` split: `light` is the base applied in both color schemes,
+ * and `dark` overrides it when the resolved scheme is dark.
+ */
+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,
+   * which the dashboard's agents page selects. A change answers the next run with the new agent
+   * and keeps the transcript, which that agent then sees as history.
+   */
+  agentId?: string | undefined;
+  /** Name shown in the widget's header. Default `"AstralBeam"`. */
+  title?: string | undefined;
+  /**
+   * Shows the widget's header, which carries the title and the reset button. `false` hides both
+   * and gives the transcript the full height. Default `true`.
+   */
+  showHeader?: boolean | undefined;
+  /** Headline shown on the empty transcript. Default `"Ask the assistant"`. */
+  emptyTitle?: string | undefined;
+  /** Subtitle shown under the empty transcript's headline. Default describes the app's tools and widgets. */
+  emptyDescription?: string | undefined;
+  /**
+   * Base URL of the AstralBeam API; the widget calls `/chat` and its subroutes under it. Read for
+   * every request, so a change moves the next one. Default `"https://app.astralbeam.ai/api"`, the
+   * hosted cloud; self-hosted deployments must set their own origin.
+   */
+  apiUrl?: string | undefined;
+  /**
+   * 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.
+   */
+  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> | undefined;
+  /** Host-rendered replacements for parts of the widget's chrome; see `AstralBeamChatSlots`. */
+  slots?: AstralBeamChatSlots | undefined;
+  /**
+   * Shows the collected sandbox panel (every file the agent wrote, with downloads, and the full
+   * command log) above the composer once the sandbox has done work. Off by default: the
+   * transcript already shows each step where it happened. Default `false`.
+   */
+  sandboxPanel?: boolean | undefined;
+  /**
+   * File attachments in the composer, on by default. `false` turns them off; an options object
+   * narrows the limits and accepted types.
+   */
+  attachments?: boolean | AstralBeamChatAttachmentOptions | undefined;
+  /** Color scheme of the widget. Default `"system"`. */
+  colorScheme?: AstralBeamChatColorScheme | undefined;
+  /** Custom values for the widget's theming CSS variables, per color scheme. */
+  theme?: AstralBeamChatTheme | undefined;
+  /**
+   * Logs every SDK action to the browser console with UTC timestamps and full payloads,
+   * and asks the endpoint (via the forwarded props) to log its side of the run too.
+   */
+  debug?: boolean | undefined;
+}
 //#endregion
 //#region src/lib/debug.d.ts
 declare const CATEGORY_COLORS: {
@@ -3608,26 +3722,38 @@ interface WidgetRenderRequest {
   props: Record<string, unknown>;
   /** Keys the render: a repeat of the same call replaces its own render, not another's. */
   toolCallId: string;
-}
-interface AstralBeamChatCoreOptions {
-  /** Public ID of the organization-owned agent; omitted, the organization's default answers. */
-  agentId?: string | undefined;
-  /** Base URL of the AstralBeam API; `/chat` hangs off it. Default the hosted cloud. */
-  apiUrl?: string | undefined;
   /**
-   * Where short-lived chat JWTs come from: `{ url, ...RequestInit }` for a token endpoint, or a
-   * function minting `{ token }` in the host page. Either runs again on every renewal.
-   * Default `{ url: "/api/astralbeam/token" }`.
+   * Drops this session's copy of the render's cleanup, for a host that disposed the render itself;
+   * without it the cleanup — and the DOM it captures — is held until the next reset.
    */
-  fetchChatAuthToken?: AstralBeamChatAuthTokenSource | undefined;
-  /** Host tools the agent can call; `execute` runs wherever this session lives. */
-  tools?: Record<string, ToolDefinition> | undefined;
-  /** Widgets declared to the agent; `onRenderWidget` is asked to draw them. */
+  release: () => void;
+}
+/**
+ * Mirrors of the underlying chat client's stream lifecycle, for a consumer that logs or traces the
+ * raw run; the drop-in widget passes its debug console logger here.
+ */
+interface ChatStreamCallbacks {
+  onChunk?: ((chunk: StreamChunk) => void) | undefined;
+  onResponse?: ((response?: Response) => void) | undefined;
+  onFinish?: ((message: UIMessage) => void) | undefined;
+  onError?: ((error: Error) => void) | undefined;
+}
+/**
+ * The transport and tool options of the drop-in widget, minus everything about its UI, plus this
+ * session's own rendering hooks. The shared options are documented on `MountAstralBeamChatOptions`.
+ */
+interface AstralBeamChatCoreOptions extends Pick<MountAstralBeamChatOptions, "agentId" | "apiUrl" | "fetchChatAuthToken" | "tools" | "debug"> {
+  /** Widgets declared to the agent, without a `render`; `onRenderWidget` is asked to draw them. */
   widgets?: Record<string, WidgetDeclaration> | undefined;
   /** Draws an agent-requested widget however the host wants; may return a cleanup. */
   onRenderWidget?: ((request: WidgetRenderRequest) => (() => void) | void) | undefined;
-  /** Logs every action to the console and asks the endpoint to log its side too. */
-  debug?: boolean | undefined;
+  /** Stream lifecycle callbacks, read per event so they follow an update. */
+  streamCallbacks?: ChatStreamCallbacks | undefined;
+}
+/** One tool as declared to the agent: its name, and the `metadata.title` that labels it. */
+interface AgentToolInfo {
+  name: string;
+  title: string | undefined;
 }
 interface AstralBeamChatState {
   messages: UIMessage[];
@@ -3639,6 +3765,8 @@ interface AstralBeamChatState {
   capabilities: {
     attachments: boolean;
   };
+  /** The tool set currently declared to the agent, in declaration order. */
+  agentTools: readonly AgentToolInfo[];
   sandboxStatus: SandboxStatus | undefined;
   sandbox: SandboxActivity;
 }
@@ -3657,6 +3785,8 @@ interface AstralBeamChatCore {
   addToolResult: ChatClient["addToolResult"];
   /** Stops the in-flight generation; the transcript keeps what already streamed. */
   stop: () => void;
+  /** Mints a fresh chat auth token, ignoring the cached one; for a retry after a failure. */
+  retryAuthentication: () => void;
   /** Re-runs the last exchange. */
   reload: () => Promise<void>;
   /** Clears the conversation and disposes live widget renders. */
@@ -3724,14 +3854,7 @@ interface TypedToolDefinition<S extends ParametersSchema = JsonSchemaObject> {
   parameters?: S;
   execute: (input: InferParameters<S>) => unknown | Promise<unknown>;
 }
-interface TypedWidgetDefinition<S extends ParametersSchema = JsonSchemaObject> {
-  description: string;
-  parameters?: S;
-  render: (props: InferParameters<S>, container: HTMLElement) => (() => void) | void;
-}
 /** Declares a host tool; a Standard Schema `parameters` types (and validates) `execute`'s input. */
 declare function defineTool<const S extends ParametersSchema = JsonSchemaObject>(tool: TypedToolDefinition<S>): ToolDefinition;
-/** Declares a host widget; a Standard Schema `parameters` types (and validates) `render`'s props. */
-declare function defineWidget<const S extends ParametersSchema = JsonSchemaObject>(widget: TypedWidgetDefinition<S>): WidgetDefinition;
 //#endregion
-export { SandboxActivity as A, AstralBeamChatState as C, WidgetDeclaration as D, ChatAuthenticationState as E, InferParameters as F, JsonSchemaObject as I, ParametersSchema as L, SandboxCommandRun as M, SandboxFileWrite as N, buildAgentTools as O, SandboxStatus as P, StandardSchemaV1 as R, AstralBeamChatCoreOptions as S, createAstralBeamChat as T, sandboxRefusal as _, SANDBOX_LIST_FILES_TOOL as a, lastPartInProgress as b, SANDBOX_RUN_COMMAND_TOOL as c, collectSandboxActivity as d, describeSandboxCommandRun as f, readSandboxFileWrite as g, readSandboxCommandRun as h, RENDER_WIDGET_TOOL as i, SandboxArtifact as j, RenderWidgetInput as k, SANDBOX_STATUS_EVENT as l, readSandboxArtifact as m, defineWidget as n, SANDBOX_PUBLISH_ARTIFACT_TOOL as o, isSandboxTool as p, ASK_QUESTIONNAIRE_TOOL as r, SANDBOX_READ_FILE_TOOL as s, defineTool as t, SANDBOX_WRITE_FILE_TOOL as u, hasPendingToolRun as v, WidgetRenderRequest as w, AstralBeamChatCore as x, isSettledToolCall as y, ToolDefinition as z };
+export { RenderWidgetInput as A, ToolDefinition as B, AstralBeamChatState as C, ChatAuthenticationState as D, createAstralBeamChat as E, SandboxStatus as F, InferParameters as I, JsonSchemaObject as L, SandboxArtifact as M, SandboxCommandRun as N, WidgetDeclaration as O, SandboxFileWrite as P, ParametersSchema as R, AstralBeamChatCoreOptions as S, WidgetRenderRequest as T, hasPendingToolRun as _, SANDBOX_PUBLISH_ARTIFACT_TOOL as a, AgentToolInfo as b, SANDBOX_STATUS_EVENT as c, describeSandboxCommandRun as d, isSandboxTool as f, sandboxRefusal as g, readSandboxFileWrite as h, SANDBOX_LIST_FILES_TOOL as i, SandboxActivity as j, buildAgentTools as k, SANDBOX_WRITE_FILE_TOOL as l, readSandboxCommandRun as m, ASK_QUESTIONNAIRE_TOOL as n, SANDBOX_READ_FILE_TOOL as o, readSandboxArtifact as p, RENDER_WIDGET_TOOL as r, SANDBOX_RUN_COMMAND_TOOL as s, defineTool as t, collectSandboxActivity as u, isSettledToolCall as v, ChatStreamCallbacks as w, AstralBeamChatCore as x, lastPartInProgress as y, StandardSchemaV1 as z };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
-import { C as AstralBeamChatState, S as AstralBeamChatCoreOptions, x as AstralBeamChatCore } from "./index-TbZxlv54.js";
+import { C as AstralBeamChatState, S as AstralBeamChatCoreOptions, x as AstralBeamChatCore } from "./index-CudekMKM.js";
 import { ReactNode } from "react";
-import { AstralBeamChatAttachmentOptions, AstralBeamChatAuthTokenRequest, AstralBeamChatAuthTokenSource, AstralBeamChatColorScheme, AstralBeamChatTheme, InferParameters, JsonSchemaObject, ParametersSchema, ToolDefinition, WidgetDefinition as WidgetDefinition$1, defineTool } from "@astralbeam/sdk/client";
+import { AstralBeamChatAttachmentOptions, AstralBeamChatAuthTokenRequest, AstralBeamChatAuthTokenSource, AstralBeamChatColorScheme, AstralBeamChatTheme, InferParameters, JsonSchemaObject, MountAstralBeamChatOptions, ParametersSchema, ToolDefinition, WidgetDefinition as WidgetDefinition$1, defineTool } from "@astralbeam/sdk/client";
 
 //#region src/react/index.d.ts
 interface WidgetDefinition extends Omit<WidgetDefinition$1, "render"> {
@@ -38,59 +38,20 @@ interface AstralBeamChatRef {
   /** Stops the in-flight generation, if any; the transcript keeps what already streamed. */
   stop: () => void;
 }
-interface AstralBeamChatProps {
-  /**
-   * Public ID of the organization-owned agent. Omit it to use the organization's default agent,
-   * which the dashboard's agents page selects. A change answers the next run with the new agent
-   * and keeps the transcript, which that agent then sees as history.
-   */
-  agentId?: string;
-  /** Name shown in the widget's header. Default `"AstralBeam"`. */
-  title?: string;
-  /**
-   * Shows the widget's header with the title and the reset button; `false` hides both and gives
-   * the transcript the full height. Default `true`.
-   */
-  showHeader?: boolean;
+/**
+ * Every mount option as a prop, with the DOM-rendering fields replaced by React ones: a widget
+ * renders JSX, and the chrome slots take nodes instead of renderers. The shared options are
+ * documented once, on `MountAstralBeamChatOptions`.
+ */
+interface AstralBeamChatProps extends Omit<MountAstralBeamChatOptions, "widgets" | "slots"> {
+  /** Host-defined widgets the agent can render inline in the conversation, keyed by identifier. */
+  widgets?: Record<string, WidgetDefinition> | undefined;
   /** Replaces the header's content with the host's own React content; `showHeader` still applies. */
   header?: ReactNode;
   /** Replaces the empty-transcript state with the host's own React content. */
   empty?: ReactNode;
   /** Extra host controls at the end of the composer's button row, next to send. */
   composerActions?: ReactNode;
-  /** Headline shown on the empty transcript. Default `"Ask the assistant"`. */
-  emptyTitle?: string;
-  /** Subtitle under the empty transcript's headline. */
-  emptyDescription?: string;
-  /**
-   * Base URL of the AstralBeam API; the widget calls `/chat` under it. Read per request, so a
-   * change moves the next one. Default the hosted cloud.
-   */
-  apiUrl?: string;
-  /**
-   * Where the short-lived chat JWT comes from: `{ url, ...RequestInit }` for a token endpoint, or
-   * a function minting `{ token }`, optionally a promise, in the host app. Read per token, and
-   * the function form runs in the host's React tree, so an inline closure over current auth state
-   * is fine and needs no memoization. Default `{ url: "/api/astralbeam/token" }`.
-   */
-  fetchChatAuthToken?: AstralBeamChatAuthTokenSource;
-  /** Host-defined tools the agent can call, executed in the host's React app, keyed by name. */
-  tools?: Record<string, ToolDefinition>;
-  /** Host-defined widgets the agent can render inline in the conversation, keyed by identifier. */
-  widgets?: Record<string, WidgetDefinition>;
-  /** Color scheme of the chat widget. Default `"system"`. */
-  colorScheme?: AstralBeamChatColorScheme;
-  /** Custom values for the widget's theming CSS variables, per color scheme. */
-  theme?: AstralBeamChatTheme | undefined;
-  /** File attachments in the composer, on by default; `false` turns them off. */
-  attachments?: boolean | AstralBeamChatAttachmentOptions;
-  /** Shows the collected sandbox panel (files with downloads, command log) above the composer. Default `false`. */
-  sandboxPanel?: boolean;
-  /**
-   * Logs every SDK action to the browser console with UTC timestamps and full payloads,
-   * and asks the endpoint to log its side of the run too.
-   */
-  debug?: boolean;
 }
 declare const AstralBeamChat: import("react").ForwardRefExoticComponent<AstralBeamChatProps & import("react").RefAttributes<AstralBeamChatRef>>;
 //#endregion

package/dist/react.js

@@ -1,4 +1,4 @@
-import { C as DEFAULT_COLOR_SCHEME, r as createAstralBeamChat } from "./core-DYXxodYg.js";
+import { C as DEFAULT_COLOR_SCHEME, n as CORE_OPTION_KEYS, r as createAstralBeamChat } from "./core-BF1G1dLe.js";
 import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createPortal } from "react-dom";
 import { defineTool, mountAstralBeamChat } from "@astralbeam/sdk/client";
@@ -15,19 +15,12 @@ function defineWidget(widget) {
 * state stay live and nothing needs a remount.
 */
 function useAstralBeamChat(options) {
-	const [core] = useState(() => createAstralBeamChat(options));
+	const coreRef = useRef(null);
+	coreRef.current ??= createAstralBeamChat(options);
+	const core = coreRef.current;
 	useEffect(() => {
 		core.updateOptions(options);
-	}, [
-		core,
-		options.agentId,
-		options.apiUrl,
-		options.fetchChatAuthToken,
-		options.tools,
-		options.widgets,
-		options.onRenderWidget,
-		options.debug
-	]);
+	}, [core, ...CORE_OPTION_KEYS.map((key) => options[key])]);
 	useEffect(() => () => core.dispose(), [core]);
 	return {
 		...useSyncExternalStore(core.subscribe, core.getState, core.getState),