@astralbeam/sdk 0.4.2 → 0.6.0

package/README.md

@@ -33,29 +33,36 @@ const handle = mountAstralBeamChat(document.getElementById("sidebar"), {})
 
 ## 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,26 +71,26 @@ 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.
-- The widget POSTs `authTokenUrl` with the page's cookies; pass `authTokenHeaders` (an object, or a function for a rotating credential) when your backend is on another origin behind header auth.
+- `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
 
-Every option is also a prop on `<AstralBeamChat>`; `handle.update(options)` applies any subset in place. `agentId`, `apiUrl`, `authTokenUrl`, and `authTokenHeaders` are fixed at mount. Details in [Configuration](https://app.astralbeam.ai/docs/sdk/configuration).
-
-| Option                               | Default                         | Meaning                                                         |
-| ------------------------------------ | ------------------------------- | --------------------------------------------------------------- |
-| `agentId`                            | organization's default          | `agt_<organization>_<agent>` from the dashboard                 |
-| `apiUrl`                             | `https://app.astralbeam.ai/api` | Base URL of the AstralBeam API; the widget calls `/chat` there  |
-| `authTokenUrl`                       | `/api/astralbeam/token`         | Your token endpoint                                             |
-| `authTokenHeaders`                   | none                            | Extra token-request headers, for a backend on another origin    |
-| `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                   |
-| `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) |
-| `debug`                              | `false`                         | Log every SDK action in the browser and on the server           |
+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).
+
+| Option                               | Default                            | Meaning                                                            |
+| ------------------------------------ | ---------------------------------- | ------------------------------------------------------------------ |
+| `agentId`                            | organization's default             | `agt_<organization>_<agent>` 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          |
+| `emptyTitle`, `emptyDescription`     | generic copy                       | Headline and subtitle of the empty transcript                      |
+| `colorScheme`, `theme`               | `"system"`, built-in palette       | Light/dark/system, and shadcn token overrides                      |
+| `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)    |
+| `debug`                              | `false`                            | Log every SDK action in the browser and on the server              |
 
 A `ref` on `<AstralBeamChat>` (and the vanilla handle) exposes `reset()` and `stop()` for hosts that draw their own controls.
 
@@ -133,13 +140,13 @@ 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                 |
+| `@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

@@ -99,10 +99,27 @@ type AstralBeamChatColorScheme = "light" | "dark" | "system";
 /** Overrides for the widget's theming CSS variables, keyed by custom-property name (`"--primary"`). */
 type AstralBeamChatThemeVariables = Record<`--${string}`, string>;
 /**
- * Headers added to the token request: an object for a fixed credential, or a function for one the
- * host must read or await per request, such as a rotating access token.
+ * 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`,
+ * `credentials: "include"`, `cache: "no-store"`, and an `accept: application/json` header, each
+ * overridable here, and the response is expected to carry `{ token }` as JSON.
  */
-type AstralBeamChatAuthTokenHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+interface AstralBeamChatAuthTokenRequest extends RequestInit {
+  url: string;
+}
+/**
+ * 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 AstralBeamChatAuthTokenSource = AstralBeamChatAuthTokenRequest | (() => {
+  token: string;
+} | 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, ...),
@@ -115,8 +132,9 @@ interface AstralBeamChatTheme {
 }
 interface MountAstralBeamChatOptions {
   /**
-   * Public ID of the organization-owned agent, fixed for this mounted chat. Omit it to use the
-   * organization's default agent, which the dashboard's agents page selects.
+   * 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"`. */
@@ -131,20 +149,18 @@ interface MountAstralBeamChatOptions {
   /** 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. Fixed at
-   * mount. Default `"https://app.astralbeam.ai/api"`, the hosted cloud; self-hosted deployments
-   * must set their own origin.
+   * 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;
-  /** Application endpoint that mints a short-lived chat JWT. Fixed at mount. Default `"/api/astralbeam/token"`. */
-  authTokenUrl?: string | undefined;
   /**
-   * Extra request headers for `authTokenUrl`, for hosts whose backend sits on another origin and
-   * authenticates with a bearer token or a custom header rather than the page's cookies. Resolved
-   * again on every token request, so pass the function form for a credential that rotates.
-   * Fixed at mount.
+   * 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.
    */
-  authTokenHeaders?: AstralBeamChatAuthTokenHeaders | 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. */
@@ -173,10 +189,11 @@ interface MountAstralBeamChatOptions {
   debug?: boolean | undefined;
 }
 /**
- * Mount options the handle can change afterwards. The agent and the transport URLs are fixed:
- * changing any of them would mean a new client and a discarded transcript.
+ * What the handle's `update` takes: every mount option, none of them fixed. The transport options
+ * are re-read per request rather than captured, so changing them keeps the transcript and the
+ * chat session instead of forcing a fresh mount.
  */
-type AstralBeamChatUpdate = Partial<Omit<MountAstralBeamChatOptions, "agentId" | "apiUrl" | "authTokenUrl" | "authTokenHeaders">>;
+type AstralBeamChatUpdate = Partial<MountAstralBeamChatOptions>;
 interface AstralBeamChatHandle {
   unmount: () => void;
   /**
@@ -210,4 +227,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 AstralBeamChatAuthTokenHeaders, 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 };
+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-C6NW94JW.js`).then(({renderChat:e})=>{a?.(`mount`,`chat chunk loaded`),f||(p=e(o,s,i))}),{update:e=>{if(Object.hasOwn(e,`agentId`)||Object.hasOwn(e,`apiUrl`)||Object.hasOwn(e,`authTokenUrl`)||Object.hasOwn(e,`authTokenHeaders`))throw Error(`agentId, apiUrl, authTokenUrl, and authTokenHeaders are fixed at mount`);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-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};

package/dist/{core-2LtbAqiQ.js → core-DYXxodYg.js}

@@ -7842,50 +7842,51 @@ 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 postChatToken(options, signal) {
-	const { authTokenUrl, authTokenHeaders, fetchClient } = options;
-	const headers = new Headers({ accept: "application/json" });
-	if (authTokenHeaders) {
-		const extra = typeof authTokenHeaders === "function" ? await authTokenHeaders() : authTokenHeaders;
-		for (const [name, value] of Object.entries(extra)) headers.set(name, value);
-	}
-	const response = await fetchClient(authTokenUrl, {
+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, {
 		method: "POST",
-		headers,
 		credentials: "include",
 		cache: "no-store",
-		signal
+		...init,
+		headers,
+		signal: init.signal ? AbortSignal.any([signal, init.signal]) : 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.fetchChatAuthToken === "function" ? "fetchChatAuthToken" : "Authentication endpoint";
 	try {
-		const token = await postChatToken(options, signal);
-		if (typeof token !== "string" || !token) throw new Error("Authentication endpoint did not return a token");
+		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("Authentication endpoint returned an expired token");
+		if (expiresAt <= Date.now()) throw new Error(`${source} returned an expired token`);
 		session.cached = {
 			value: token,
 			expiresAt
@@ -7905,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;
@@ -7921,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();
@@ -7934,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
 	});
@@ -8081,9 +8082,8 @@ function describeSandboxCommandRun(run) {
 * whole UI is another.
 */
 function createAstralBeamChat(options) {
-	const debug = createDebugLogger(options.debug);
-	const urls = chatApiUrls(options.apiUrl);
-	const widgets = options.widgets ?? {};
+	let live = { ...options };
+	let debug = createDebugLogger(live.debug);
 	const listeners = /* @__PURE__ */ new Set();
 	let state = {
 		messages: [],
@@ -8105,8 +8105,7 @@ function createAstralBeamChat(options) {
 		for (const listener of listeners) listener();
 	};
 	const authentication = {
-		authTokenUrl: options.authTokenUrl ?? "/api/astralbeam/token",
-		authTokenHeaders: options.authTokenHeaders,
+		fetchChatAuthToken: live.fetchChatAuthToken ?? { url: "/api/astralbeam/token" },
 		session: {
 			cached: void 0,
 			refreshPromise: void 0,
@@ -8117,11 +8116,11 @@ function createAstralBeamChat(options) {
 		debug
 	};
 	initializeChatAuthentication(authentication).catch(() => void 0);
-	(async () => {
+	const resolveCapabilities = async () => {
 		try {
-			const url = new URL(urls.config, globalThis.location?.href);
-			if (options.agentId) url.searchParams.set("agentId", options.agentId);
-			const token = await getValidChatToken(authentication);
+			const url = new URL(chatApiUrls(live.apiUrl).config, globalThis.location?.href);
+			if (live.agentId) url.searchParams.set("agentId", live.agentId);
+			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();
@@ -8129,20 +8128,22 @@ function createAstralBeamChat(options) {
 		} catch (error) {
 			debug?.("error", "agent capabilities could not be resolved; keeping the defaults", error);
 		}
-	})();
+	};
+	resolveCapabilities();
 	const renderCleanups = /* @__PURE__ */ new Map();
 	const disposeRenders = () => {
 		for (const cleanup of renderCleanups.values()) cleanup();
 		renderCleanups.clear();
 	};
 	const renderWidget = async (input, toolCallId) => {
+		const widgets = live.widgets ?? {};
 		if (!Object.hasOwn(widgets, input.widget)) throw new Error(`Unknown widget "${input.widget}"`);
 		const declaration = widgets[input.widget];
 		const validated = await validateParameters(declaration?.parameters, input.props ?? {});
 		if (validated == null) throw new Error(`Props for widget "${input.widget}" failed validation`);
 		renderCleanups.get(toolCallId)?.();
 		renderCleanups.delete(toolCallId);
-		const cleanup = options.onRenderWidget?.({
+		const cleanup = live.onRenderWidget?.({
 			widget: input.widget,
 			props: validated,
 			toolCallId
@@ -8150,23 +8151,25 @@ function createAstralBeamChat(options) {
 		if (cleanup) renderCleanups.set(toolCallId, cleanup);
 		return {
 			widget: input.widget,
-			rendered: options.onRenderWidget !== void 0
+			rendered: live.onRenderWidget !== void 0
 		};
 	};
+	const agentTools = () => buildAgentTools(live.widgets ?? {}, live.tools ?? {}, renderWidget, debug);
+	const forwardedProps = () => ({
+		...live.agentId ? { agentId: live.agentId } : {},
+		...live.debug ? { debug: true } : {}
+	});
 	const client = new ChatClient({
-		connection: fetchServerSentEvents(urls.chat, async () => ({
-			headers: { authorization: `Bearer ${await getValidChatToken(authentication)}` },
+		connection: fetchServerSentEvents(() => chatApiUrls(live.apiUrl).chat, async () => ({
+			headers: { authorization: `Bearer ${await getValidChatAuthToken(authentication)}` },
 			fetchClient: (input, init) => fetchAuthenticatedChat({
 				...authentication,
 				input,
 				init
 			})
 		})),
-		tools: buildAgentTools(widgets, options.tools ?? {}, renderWidget, debug),
-		forwardedProps: {
-			...options.agentId ? { agentId: options.agentId } : {},
-			...options.debug ? { debug: true } : {}
-		},
+		tools: agentTools(),
+		forwardedProps: forwardedProps(),
 		onMessagesChange: (messages) => {
 			update({
 				messages,
@@ -8213,6 +8216,22 @@ function createAstralBeamChat(options) {
 			listeners.add(listener);
 			return () => listeners.delete(listener);
 		},
+		updateOptions: (next) => {
+			const agent = live.agentId;
+			const apiUrl = live.apiUrl;
+			live = {
+				...live,
+				...next
+			};
+			debug = createDebugLogger(live.debug);
+			authentication.fetchChatAuthToken = live.fetchChatAuthToken ?? { url: "/api/astralbeam/token" };
+			authentication.debug = debug;
+			client.updateOptions({
+				tools: agentTools(),
+				forwardedProps: forwardedProps()
+			});
+			if (live.agentId !== agent || live.apiUrl !== apiUrl) resolveCapabilities();
+		},
 		sendMessage: (content) => {
 			settleDanglingToolCalls();
 			return client.sendMessage(content);

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-DJWIt_VP.js";
+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 };

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-2LtbAqiQ.js";
+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 };

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

@@ -3306,10 +3306,27 @@ interface ToolDefinition {
   execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
 }
 /**
- * Headers added to the token request: an object for a fixed credential, or a function for one the
- * host must read or await per request, such as a rotating access token.
+ * 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`,
+ * `credentials: "include"`, `cache: "no-store"`, and an `accept: application/json` header, each
+ * overridable here, and the response is expected to carry `{ token }` as JSON.
  */
-type AstralBeamChatAuthTokenHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+interface AstralBeamChatAuthTokenRequest extends RequestInit {
+  url: string;
+}
+/**
+ * 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 AstralBeamChatAuthTokenSource = AstralBeamChatAuthTokenRequest | (() => {
+  token: string;
+} | undefined | Promise<{
+  token: string;
+} | undefined>);
 //#endregion
 //#region src/lib/debug.d.ts
 declare const CATEGORY_COLORS: {
@@ -3597,14 +3614,12 @@ interface AstralBeamChatCoreOptions {
   agentId?: string | undefined;
   /** Base URL of the AstralBeam API; `/chat` hangs off it. Default the hosted cloud. */
   apiUrl?: string | undefined;
-  /** The application endpoint that mints short-lived chat JWTs. Default `/api/astralbeam/token`. */
-  authTokenUrl?: string | undefined;
   /**
-   * Extra headers for the token request, for a backend on another origin that authenticates with a
-   * bearer token or custom header instead of cookies. Resolved on every token request, so pass the
-   * function form for a credential that rotates.
+   * 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" }`.
    */
-  authTokenHeaders?: AstralBeamChatAuthTokenHeaders | undefined;
+  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. */
@@ -3631,6 +3646,11 @@ interface AstralBeamChatCore {
   getState: () => AstralBeamChatState;
   /** Notifies on every state change; returns the unsubscribe. */
   subscribe: (listener: () => void) => () => void;
+  /**
+   * Merges option changes into the session and applies them in place, keeping the transcript and
+   * the chat session. Only the keys given are replaced.
+   */
+  updateOptions: (options: Partial<AstralBeamChatCoreOptions>) => void;
   /** Sends a message, first settling any dangling tool calls so the run can proceed. */
   sendMessage: (content: string | MultimodalContent) => Promise<void>;
   /** Resolves a client tool call the host executed itself (a questionnaire, an approval). */