@astralbeam/sdk 0.0.5 → 0.1.0

package/README.md

@@ -1,171 +1,135 @@
 # @astralbeam/sdk
 
-Frontend SDK for [AstralBeam](https://astralbeam.ai): drop-in, fully-customizable agent UI with managed chat streaming, conversation history, and observability.
-
-> Work in progress: the chat streams from a real agent endpoint (an AstralBeam webapp exposing `/api/chat`), with optional host-backed authentication, streaming messages, tool calls executed in the host page, in-chat questionnaires, and host-rendered widgets. Conversation history is not built yet.
-
-## Installation
+A drop-in agent chat sidebar for your web app, from [AstralBeam](https://astralbeam.ai), with a headless core underneath when you want to own the UI. The widget renders in a shadow root so its styles never mix with yours, and it streams from an AstralBeam chat endpoint.
 
 ```sh
 npm install @astralbeam/sdk
 ```
 
-## Usage
+## Quick start
 
-### Vanilla (any web app)
+One component in React, one function everywhere else. Full setup, including the required token endpoint, is in [Getting started](https://app.astralbeam.ai/docs/sdk/getting-started).
 
-`@astralbeam/sdk/client` is a tiny framework-agnostic loader with no dependencies of its own; the React-based chat widget is bundled into a lazily loaded chunk, so the host page does not need React.
+```tsx
+import { AstralBeamChat } from "@astralbeam/sdk/react"
+
+export function Sidebar() {
+  return <AstralBeamChat />
+}
+```
 
 ```ts
 import { mountAstralBeamChat } from "@astralbeam/sdk/client"
 
-const sidebar = document.getElementById("sidebar")
-const handle = mountAstralBeamChat(sidebar, {
-  title: "Dashboard assistant", // name in the widget header (default "AstralBeam")
-  showHeader: true, // header with the title and the reset button (default true)
-  chatEndpoint: "https://myapp.example/api/chat", // AstralBeam chat endpoint (default "/api/chat")
-  authEndpoint: "/api/astralbeam/token", // host endpoint minting the chat token (required today)
-  systemPrompt: "You are the assistant of an infrastructure dashboard.",
-  colorScheme: "system", // "light" | "dark" | "system" (default)
-  theme: {
-    // custom values for the widget's theming CSS variables (all optional)
-    light: { "--primary": "#b4762a", "--radius": "0px" },
-    dark: { "--primary": "#d99a45" },
-  },
-  attachments: { maxFiles: 3 }, // file attachments in the composer (on by default; false to hide)
-  debug: false, // log every SDK and endpoint action to the consoles (default false)
-  tools: {
-    restart_service: {
-      metadata: { title: "Restart a service" }, // transcript label; defaults to the tool's name
-      description: "Restart one of the host app's services by name",
-      parameters: {
-        type: "object",
-        properties: { service: { type: "string" } },
-        required: ["service"],
-      },
-      execute: async ({ service }) => await restartService(String(service)),
-    },
-  },
-  widgets: {
-    systemStatus: {
-      description: "Shows the current status of the host app's systems",
-      parameters: {
-        type: "object",
-        properties: { degraded: { type: "boolean" } },
-      },
-      render: (props, container) => {
-        container.textContent = props.degraded ? "Degraded performance" : "All systems operational"
-      },
-    },
-  },
-})
-// later: handle.update({ colorScheme: "dark", widgets: nextWidgets }), handle.unmount()
+const handle = mountAstralBeamChat(document.getElementById("sidebar"), {})
+// handle.update({ colorScheme: "dark" }) — handle.unmount()
 ```
 
-The chat widget renders inside a shadow root on the mount target, so its styles never leak into (or absorb from) the host page. It streams the conversation from the `chatEndpoint` (an AstralBeam webapp's `/api/chat`), forwarding the optional `systemPrompt` for the endpoint to append to the agent's instructions. When `authEndpoint` is present, the widget obtains a short-lived bearer token before enabling its composer and renews it in memory as needed. The AstralBeam endpoint currently answers unauthenticated runs with `401`, so `authEndpoint` is required in practice. The `title` option names the assistant in the widget's header, and `showHeader: false` hides that header — title and reset button both — giving the transcript the widget's full height. Assistant replies are rendered as Markdown (headings, lists, tables, links, and fenced code) with [TanStack Markdown](https://tanstack.com/markdown), using its streaming profile so a partial reply stays stable as it arrives; raw HTML in a reply is escaped and executable link protocols are dropped. The `colorScheme` option picks the widget's color scheme — `"system"` (the default) follows the OS `prefers-color-scheme` setting live. The `theme` option overrides the widget's theming CSS variables — the [shadcn/ui tokens](https://ui.shadcn.com/docs/theming) such as `--background`, `--primary`, `--radius`, and the `--font-sans`/`--font-heading`/`--font-mono` font stacks — per color scheme: mirroring shadcn's `:root`/`.dark` split, `theme.light` is the base applied in both schemes and `theme.dark` overrides it when the resolved scheme is dark.
-
-### Attachments
+- 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 `chatEndpoint` 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`.
+- Mount it above your router if the transcript should survive page navigation.
 
-The composer takes files by default: through the paperclip button, by dropping them on the composer, or by pasting them (a pasted screenshot lands as an image). Each file appears as a chip above the input, removable before the message is sent and shown again with the message in the transcript, where clicking one downloads the file. Images and PDFs go to the model as-is; a text file (`.md`, `.csv`, `.json`, source files, ...) is read as text by the endpoint, which labels it with its filename. A file the widget cannot send keeps its chip and says why, and one the endpoint cannot use is explained to the agent in the conversation rather than failing the run — so the assistant can tell the user. Files are sent inline with the message, and stay in the conversation's context for the rest of the run.
+## Authentication
 
-Set `attachments: false` to hide the feature entirely, or pass an options object to narrow it:
+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).
 
-| Option          | Default                                    | Meaning                                                                      |
-| --------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
-| `enabled`       | `true`                                     | `false` is the same as `attachments: false`                                  |
-| `maxFiles`      | `5`                                        | Files per message                                                            |
-| `maxFileBytes`  | per kind: 5 MB image, 10 MB PDF, 1 MB text | Ceiling for one file; the per-kind caps still apply, so the smaller one wins |
-| `maxTotalBytes` | 20 MB                                      | Ceiling for all files on one message                                         |
-| `accept`        | everything supported                       | MIME types or `type/*` patterns, e.g. `["image/*"]` for images only          |
+```ts
+import { createAstralBeamTokenRoute } from "@astralbeam/sdk/server"
 
-The endpoint enforces the same size and type limits independently, so narrowing them in the widget is a UI affordance rather than a security boundary.
+export const POST = createAstralBeamTokenRoute({
+  apiKey: () => process.env.ASTRALBEAM_API_KEY, // key_<organization>_<key>_abo_<secret>
+  tenantUser: async (request) => {
+    const session = await getApplicationSession(request)
+    return session && { id: session.user.id, name: session.user.name }
+  },
+})
+```
 
-`handle.update(options)` replaces any subset of the mount options in place, keeping the transcript, the chat session, and live widget renders: rename the assistant, retheme it alongside the host app, revise the `systemPrompt`, retune or disable `attachments`, register or drop `tools` and `widgets`, or turn `debug` on mid-conversation. Newly declared tools and widgets reach the agent on its next run. `chatEndpoint` and `authEndpoint` are fixed at mount because they construct the transport. Dropping a widget disposes any render of it still in the transcript, which falls back to a summary marker.
+- 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`.
+- Derive `tenantUser` from trusted server-side state, never from anything the browser sent.
+- Tokens are signed, not encrypted: never put a secret in them.
+- Lifetimes are 60–600 seconds; the SDK renews in memory before expiry.
 
-With `debug: true` (also available as a prop on `<AstralBeamChat>`), every SDK action — mounting, theming, sends, streamed messages and reasoning, tool calls and their host-side executions, widget renders, questionnaire answers, errors — is logged to the browser console with UTC timestamps and full payloads, and the endpoint is asked to log its side of the same run to the server console, so a conversation can be followed end to end.
+## Options
 
-The agent acts on the host app through **tools** and **widgets**, both keyed by name and declared to the agent with a `description` and a `parameters` schema — either a plain JSON Schema object as above or any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType, ...), with no validator dependency required. A Standard Schema is also enforced client-side, validating the agent-chosen input before host code runs; with a plain JSON Schema, treat the input as untrusted. A tool's `execute` runs in the host page and its resolved value streams back to the agent as the tool result. Every tool call becomes one line in the transcript that expands to show the call's input and output as JSON; a tool's `metadata`, forwarded verbatim to the tool definition, labels that line with its `title` in place of the registry name. A widget's `render` draws host UI into the conversation: the SDK creates a light-DOM child of the mount target, calls `render(props, container)` on it, and projects it into the transcript through a named `<slot>`; `render` may return a cleanup function.
+Every option is also a prop on `<AstralBeamChat>`; `handle.update(options)` applies any subset in place. `agentId`, `chatEndpoint`, and `authEndpoint` are fixed at mount. Details in [Configuration](https://app.astralbeam.ai/docs/sdk/configuration).
 
-Widget renders pick up the host page's typography and custom properties automatically. That needs help, because slotted content inherits through the [flattened tree](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scoping), whose parent for a render is the `<slot>` inside the chat's shadow root — so a render would otherwise inherit the chat's own font and colors, and resolve `var(--card)` against the chat's token of that name instead of yours. The SDK writes one rule into the chat's shadow root giving every widget slot the page's computed value for each inherited CSS property, plus every custom property declared in the page's stylesheets, and re-reads it when a theme class changes on an ancestor. Your own selectors match a render normally and override the mirrored values, so styling a widget is ordinary CSS with no slot-specific rules. Two limits: properties are read from the mount target's parent, so rules targeting the mount target itself are not picked up, and tokens declared only in a cross-origin stylesheet cannot be read.
+| Option                               | Default                              | Meaning                                                         |
+| ------------------------------------ | ------------------------------------ | --------------------------------------------------------------- |
+| `agentId`                            | organization's default               | `agt_<organization>_<agent>` from the dashboard                 |
+| `chatEndpoint`                       | `https://app.astralbeam.ai/api/chat` | The AstralBeam chat endpoint the widget streams from            |
+| `authEndpoint`                       | `/api/astralbeam/token`              | Your token endpoint                                             |
+| `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           |
 
-### Authentication
+A `ref` on `<AstralBeamChat>` (and the vanilla handle) exposes `reset()` and `stop()` for hosts that draw their own controls.
 
-Supply `authEndpoint`; the AstralBeam endpoint serves signed-in users only for now and rejects a run with no token, so a widget without it can stream nothing. The host endpoint must authenticate the application's existing session, load the active user and tenant from trusted server-side state, and return `{ "token": "..." }`. The SDK calls it with `POST`, `credentials: "include"`, and `cache: "no-store"`, keeps the token only in memory, refreshes it within one minute of expiry, and retries one rejected chat request with a fresh token. A configured endpoint fails closed: its loading or error state disables the composer instead of falling back to guest chat.
+## Tools and widgets
 
-Use the server entry to mint the token without exposing the signing secret to browser code:
+A tool does something: its `execute` runs in your page. A widget shows something: its `render` draws your UI into the conversation. Both are declared with a `description` and a `parameters` schema. See [Tools and widgets](https://app.astralbeam.ai/docs/sdk/tools-and-widgets).
 
-```ts
-import { createAstralBeamChatToken } from "@astralbeam/sdk/server"
-
-export async function POST(request: Request) {
-  const session = await requireApplicationSession(request)
-  const token = await createAstralBeamChatToken({
-    secret: process.env.ASTRALBEAM_CHAT_AUTH_SECRET!,
-    user: {
-      id: session.user.id,
-      name: session.user.name,
-      email: session.user.email,
-      avatarUrl: session.user.avatarUrl,
-    },
-    tenant: {
-      id: session.tenant.id,
-      name: session.tenant.name,
-      logoUrl: session.tenant.logoUrl,
-    },
-  })
-  return Response.json({ token }, { headers: { "cache-control": "no-store" } })
+```tsx
+tools: {
+  restart_service: {
+    metadata: { title: "Restart a service" },
+    description: "Restart one of the host app's services by name",
+    parameters: { type: "object", properties: { service: { type: "string" } }, required: ["service"] },
+    execute: async ({ service }) => await restartService(String(service)),
+  },
+},
+widgets: {
+  systemStatus: {
+    description: "Shows the current status of the host app's systems",
+    parameters: { type: "object", properties: { degraded: { type: "boolean" } } },
+    render: ({ degraded }) => <StatusCard degraded={Boolean(degraded)} />,
+  },
 }
 ```
 
-The default lifetime is five minutes and the helper rejects lifetimes above ten minutes, weak secrets, missing IDs, and invalid profile URLs. User and tenant IDs are required; names, email, avatar, and logo are optional display metadata. Tokens use the temporary global issuer and key ID while AstralBeam has no application accounts. Because every integrator temporarily shares the verifier secret, these tokens must not authorize persisted tenant data, billing, or server-side actions until per-application keys are introduced.
-
-### React
-
-`@astralbeam/sdk/react` wraps the vanilla client in an `<AstralBeamChat>` component. It requires the `react` and `react-dom` peer dependencies (already present in any React app):
-
-```sh
-npm install @astralbeam/sdk react react-dom
-```
-
-Render `<AstralBeamChat>` wherever the chat sidebar should appear; it fills its container's height, mounts the chat widget on mount, and unmounts it on cleanup. The `title`, `showHeader`, `chatEndpoint`, `authEndpoint`, `systemPrompt`, and `tools` props work like the vanilla options (tool `execute` calls always reach the latest prop value, so they can close over current component state). The `colorScheme` prop (`"light" | "dark" | "system"`, default `"system"`) picks the color scheme, the `theme` prop overrides the widget's theming CSS variables per scheme, and the `attachments` prop configures or disables composer attachments — all like the vanilla options. Every prop except the fixed `chatEndpoint` and `authEndpoint` applies immediately on change — the wrapper forwards them to `handle.update` from an effect. Register widgets through the `widgets` prop — the same tool-definition shape as the vanilla client, except `render` returns JSX instead of drawing into a container. The agent reads each `description` and `parameters` to decide when to render a widget and with which props. Rendered widgets live in your app's React tree and are projected into the chat through slots, so state, context, and event handlers keep working:
+- Schemas are plain JSON Schema, or any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType).
+- Only a Standard Schema validates input in the browser; with plain JSON Schema, treat input as untrusted.
+- `defineTool` and `defineWidget` type `execute`/`render` input from a Standard Schema's output.
+- In React, `render` returns JSX in your own tree, so state, context, and handlers keep working.
+- New tools and widgets reach the agent on its next run.
 
-```tsx
-import { AstralBeamChat } from "@astralbeam/sdk/react"
+## Documentation
 
-export function Sidebar() {
-  return (
-    <AstralBeamChat
-      widgets={{
-        systemStatus: {
-          description: "Shows the current status of the host app's systems",
-          parameters: {
-            type: "object",
-            properties: { degraded: { type: "boolean" } },
-          },
-          render: ({ degraded }) => <StatusCard degraded={Boolean(degraded)} />,
-        },
-      }}
-    />
-  )
-}
-```
+Each guide is short and self-contained.
 
-The chat widget itself loads as a separate lazy chunk with its own bundled React copy and renders in a shadow root, so it neither depends on nor conflicts with your app's React version or styles. Only the thin `<AstralBeamChat>` wrapper and your widget `render` functions run on your app's React.
+- [Getting started](https://app.astralbeam.ai/docs/sdk/getting-started) — install, mount, layout requirements.
+- [Authentication](https://app.astralbeam.ai/docs/sdk/authentication) — the token endpoint and its security rules.
+- [Configuration](https://app.astralbeam.ai/docs/sdk/configuration) — every option, and what `update` can change.
+- [Theming](https://app.astralbeam.ai/docs/sdk/theming) — color schemes, CSS tokens, the shadow-root boundary.
+- [Tools and widgets](https://app.astralbeam.ai/docs/sdk/tools-and-widgets) — schemas, live state, rendering into the transcript.
+- [Attachments](https://app.astralbeam.ai/docs/sdk/attachments) — file kinds, limits, what the endpoint enforces.
+- [Sandbox](https://app.astralbeam.ai/docs/sdk/sandbox) — steps, the opt-in panel, downloads, inline images.
+- [Headless](https://app.astralbeam.ai/docs/sdk/headless) — own the whole chat UI on the same session.
+- [Security model](https://app.astralbeam.ai/docs/sdk/security) — who grants, who enforces, what the client can change.
 
 ## Entry points
 
-- `@astralbeam/sdk/client` — framework-agnostic browser client
-- `@astralbeam/sdk/server` — server-side token helpers
-- `@astralbeam/sdk/react` — React components (e.g. `<AstralBeamChat />`), requires the `react` and `react-dom` peer dependencies
-- `@astralbeam/sdk/vue` — Vue components, requires the `vue` peer dependency (placeholder)
-
-## Examples
+There is no root export. Conversation history is not built yet.
 
-[`examples/todos`](../examples/todos) is a minimal TanStack Start todos app that embeds the chat sidebar from the built package, authenticates a fixed demo identity through a server route, points the chat at a locally running webapp's `/api/chat`, and registers a todo-specific system prompt, `get_todos`/`create_todo`/`update_todo`/`delete_todo` tools, and a `todoCard` widget the agent renders into the conversation once per todo it shows — with no Tailwind or shadcn/ui of its own, to demonstrate the shadow-root style boundary.
+| 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`                |
 
-## Architecture
+## Example
 
-[ARCHITECTURE.md](./ARCHITECTURE.md) explains how the SDK is put together: the entry-point layout, the embedded-React chat widget, the shadow-root and slot boundary between chat and host, and the two-pass build.
+[`examples/todos`](../examples/todos) embeds the sidebar in a minimal TanStack Start app: a demo token route, host tools over live React state, and a `todoCard` widget. It uses no Tailwind or shadcn/ui of its own, to show the shadow-root boundary.
 
 ## License
 

package/dist/client.d.ts

@@ -1,11 +1,20 @@
-//#region src/lib/client-types.d.ts
-interface StandardSchemaV1 {
+//#region src/lib/types.d.ts
+interface StandardSchemaV1<Input = unknown, Output = Input> {
   readonly "~standard": {
     readonly version: 1;
     readonly vendor: string;
-    readonly validate: (value: unknown) => unknown;
+    readonly validate: (value: unknown) => unknown; /** Type-level only; the spec keeps it undefined at runtime. */
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
   };
 }
+/**
+ * Input type `defineTool`/`defineWidget` derive from a `parameters` schema: a Standard Schema's
+ * validated output, or untyped props for a plain JSON Schema, which nothing validates in the browser.
+ */
+type InferParameters<S extends ParametersSchema> = S extends StandardSchemaV1<any, infer O> ? O : Record<string, unknown>;
 /** A plain JSON Schema object, the same shape tool definitions use for their parameters. */
 interface JsonSchemaObject {
   type: "object";
@@ -71,6 +80,20 @@ interface AstralBeamChatAttachmentOptions {
    */
   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"`). */
@@ -86,6 +109,11 @@ interface AstralBeamChatTheme {
   dark?: AstralBeamChatThemeVariables | undefined;
 }
 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.
+   */
+  agentId?: string | undefined;
   /** Name shown in the widget's header. Default `"AstralBeam"`. */
   title?: string | undefined;
   /**
@@ -93,16 +121,30 @@ interface MountAstralBeamChatOptions {
    * and gives the transcript the full height. Default `true`.
    */
   showHeader?: boolean | undefined;
-  /** URL of the AstralBeam chat endpoint the widget streams from. Fixed at mount. Default `"/api/chat"`. */
+  /** 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;
+  /**
+   * URL of the AstralBeam chat endpoint the widget streams from. Fixed at mount. Default
+   * `"https://app.astralbeam.ai/api/chat"`, the hosted cloud; self-hosted deployments must set
+   * their own origin.
+   */
   chatEndpoint?: string | undefined;
-  /** Application endpoint that mints a short-lived chat JWT. Fixed at mount; omit for guest chat. */
+  /** Application endpoint that mints a short-lived chat JWT. Fixed at mount. Default `"/api/astralbeam/token"`. */
   authEndpoint?: string | undefined;
-  /** Host-specific instructions the endpoint appends to the agent's system prompt. */
-  systemPrompt?: string | 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>;
+  /** 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.
@@ -119,11 +161,10 @@ interface MountAstralBeamChatOptions {
   debug?: boolean | undefined;
 }
 /**
- * Mount options the handle can change afterwards. `chatEndpoint` is excluded on purpose: the
- * streaming connection is constructed once, so a new endpoint would mean a new client and a
- * discarded transcript.
+ * Mount options the handle can change afterwards. The agent and transport endpoints are fixed:
+ * changing any of them would mean a new client and a discarded transcript.
  */
-type AstralBeamChatUpdate = Partial<Omit<MountAstralBeamChatOptions, "chatEndpoint" | "authEndpoint">>;
+type AstralBeamChatUpdate = Partial<Omit<MountAstralBeamChatOptions, "agentId" | "chatEndpoint" | "authEndpoint">>;
 interface AstralBeamChatHandle {
   unmount: () => void;
   /**
@@ -131,9 +172,30 @@ interface AstralBeamChatHandle {
    * transcript, the chat session, and live widget renders. Only the keys given are replaced.
    */
   update: (options: AstralBeamChatUpdate) => void;
+  /** Clears the conversation: transcript, drafts, attachments, and live widget renders. */
+  reset: () => void;
+  /** Stops the in-flight generation, if any; the transcript keeps what already streamed. */
+  stop: () => void;
+}
+//#endregion
+//#region src/lib/define.d.ts
+interface TypedToolDefinition<S extends ParametersSchema = JsonSchemaObject> {
+  description: string;
+  metadata?: Record<string, unknown> | undefined;
+  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
-//#region src/client.d.ts
-declare function mountAstralBeamChat(target: HTMLElement, options?: MountAstralBeamChatOptions): AstralBeamChatHandle;
+//#region src/client/index.d.ts
+declare function mountAstralBeamChat(target: HTMLElement, options: MountAstralBeamChatOptions): AstralBeamChatHandle;
 //#endregion
-export { type AstralBeamChatAttachmentOptions, type AstralBeamChatColorScheme, type AstralBeamChatHandle, type AstralBeamChatTheme, type AstralBeamChatThemeVariables, type AstralBeamChatUpdate, type JsonSchemaObject, type MountAstralBeamChatOptions, type ParametersSchema, type StandardSchemaV1, type ToolDefinition, type WidgetDefinition, mountAstralBeamChat };
+export { type AstralBeamChatAttachmentOptions, 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{a as e,t}from"./client-utils-DyEcBInP.js";function n(n,r={}){let i={...r},a=t(i.debug);a?.(`mount`,`mounting chat widget`,{title:i.title??`AstralBeam`,showHeader:i.showHeader??!0,chatEndpoint:i.chatEndpoint??`/api/chat`,authentication:i.authEndpoint?`configured`:`guest`,colorScheme:i.colorScheme??`system`,theme:i.theme,systemPrompt:i.systemPrompt,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(`./chat-BlacYOz8.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)},unmount:()=>{a?.(`mount`,`unmounting chat widget`),f=!0,c.removeEventListener(`change`,d),p?.dispose(),p=void 0,s.remove()}}}export{n as mountAstralBeamChat};
+import{c as e,t}from"./debug-DBysy3en.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.`,chatEndpoint:i.chatEndpoint??`https://app.astralbeam.ai/api/chat`,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-C7XKsfTv.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,`chatEndpoint`)||Object.hasOwn(e,`authEndpoint`))throw Error(`agentId, chatEndpoint, and authEndpoint 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};