# Super Assist

> A ready-made assistant panel for React apps that reads your pages and presses your buttons, in one package. Pages introduce themselves to it and lend it their actions; a project's agent on Super Assist answers, so the host writes no backend.

---

# Add an assistant to a Next.js app

> Sign up on Super Assist, create an agent and a project, and put the project's assistant beside a Next.js page it reads and acts on.

In this tutorial you sign up on Super Assist, create an agent and a project, and put the project's assistant beside an Orders page in a new Next.js app. The assistant replies from Super Assist, answers from what the page shows, and ships an order when you ask. You write no backend.

You need Node.js and npm.

An agent answers on your organization's AI spend. The Pro plan includes some every month; the Free plan runs agents only on credits bought in **Billing**. This tutorial uses Pro.

## 1. Sign up

1. Open [superassist.app/app/sign-up](https://superassist.app/app/sign-up), fill in your name, email and password, and press **Sign up**.
2. Open the verification link Super Assist emails you.
3. Name your organization and press **Create organization**.
4. In the sidebar, open **Billing** and press **Upgrade to Pro**.

## 2. Create an agent

The agent is the assistant that answers in your app: its instructions, its model, and the skills, databases and knowledge bases it may use.

1. Open **Agents** and press **New agent**.
2. Name it `shop-assistant`.
3. Above **Instructions**, press **Start from a template** and pick **General assistant**.
4. Press **Create agent**.

For a support agent with its skills ready, press **Install a template** instead and pick `saas-support`. [Templates](https://superassist.app/dashboard/templates.md) says what to replace before it goes live.

## 3. Create a project and copy its publishable key

The project is your app on Super Assist. It holds the publishable key your pages connect with, the origins it accepts, and the agent that answers.

1. Open **Projects** and press **New project**.
2. Name it `My shop`. **Default agent** already shows `shop-assistant`, your only agent. Press **Create**.
3. On the project's page, press **Copy** beside **Publishable key**. It starts with `pk_`.

The key is safe to ship in your app's bundle: it only opens threads with the project's agent. **Allowed origins** lists `http://localhost:3000`, where your app is about to run.

## 4. Create the app

Create a Next.js app with the default setup, TypeScript, Tailwind and the App Router, and install the library:

```bash
npx create-next-app@latest my-shop --yes
cd my-shop
npm install @super-assist/react
```

That one package brings the panel, its styles and the runtime.

Put the publishable key in `.env.local`:

```sh title="my-shop/.env.local"
NEXT_PUBLIC_SUPER_ASSIST_KEY=pk_...
```

## 5. Mount the panel

Create `app/assistant.tsx`. It imports the panel's styles, connects to your project with `useAssistedRuntime`, and renders the panel inside `AssistedProvider`:

```tsx title="my-shop/app/assistant.tsx"
"use client";

import type { ReactNode } from "react";
import { AssistedPanel, AssistedProvider, useAssistedRuntime } from "@super-assist/react";
import "@super-assist/react/styles.css";

export function Assistant({ children }: { children: ReactNode }) {
  const runtime = useAssistedRuntime({ key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY! });
  return (
    <AssistedProvider runtime={runtime}>
      <main className="min-h-dvh p-6">{children}</main>
      <AssistedPanel mode="floating" threads />
    </AssistedProvider>
  );
}
```

`threads` adds a menu of your threads to the panel's header. Super Assist keeps them.

In `app/layout.tsx`, wrap the children in `Assistant`. Keep the scaffold's fonts and metadata, and change only the body:

```tsx title="my-shop/app/layout.tsx"
import { Assistant } from "./assistant";
```

```tsx title="my-shop/app/layout.tsx"
<body>
  <Assistant>{children}</Assistant>
</body>
```

## 6. See a reply

Replace `app/page.tsx` with a plain Orders page. Its orders live in state, so shipping one changes the page:

```tsx title="my-shop/app/page.tsx"
"use client";

import { useState } from "react";

type Order = { id: string; customer: string; status: "to ship" | "shipped" };

const seed: Order[] = [
  { id: "1042", customer: "Acme", status: "to ship" },
  { id: "1043", customer: "Globex", status: "to ship" },
  { id: "1045", customer: "Initech", status: "shipped" },
];

export default function Orders() {
  const [orders, setOrders] = useState(seed);
  const ship = (id: string) =>
    setOrders((all) =>
      all.map((order) => (order.id === id ? { ...order, status: "shipped" } : order)),
    );
  return (
    <ul className="flex flex-col gap-2">
      {orders.map((order) => (
        <li key={order.id} className="flex items-center gap-4">
          #{order.id} {order.customer}, {order.status}
          {order.status === "to ship" && (
            <button className="rounded border px-2 py-1 text-sm" onClick={() => ship(order.id)}>
              Ship
            </button>
          )}
        </li>
      ))}
    </ul>
  );
}
```

Start the app:

```bash
npm run dev
```

Open `http://localhost:3000`. The three orders show, and an **Assistant** button sits in the bottom-right corner. Press it and the panel opens. Ask "What can you do?".

Your agent replies from Super Assist. It can't see the orders yet, because the page hasn't introduced itself.

## 7. Let the assistant read and act

Wrap the page in `AssistedPage`, which gives it a name, instructions for working there, and its content. The content is a function, read only when the assistant asks for it. Then wrap each **Ship** button in `AssistedAction`. Every row uses the name `ship_order` with its own `id`, so the assistant sees one action that picks a row by id:

```tsx title="my-shop/app/page.tsx"
"use client";

import { AssistedAction, AssistedPage } from "@super-assist/react";
import { useState } from "react";

type Order = { id: string; customer: string; status: "to ship" | "shipped" };

const seed: Order[] = [
  { id: "1042", customer: "Acme", status: "to ship" },
  { id: "1043", customer: "Globex", status: "to ship" },
  { id: "1045", customer: "Initech", status: "shipped" },
];

export default function Orders() {
  const [orders, setOrders] = useState(seed);
  const ship = (id: string) =>
    setOrders((all) =>
      all.map((order) => (order.id === id ? { ...order, status: "shipped" } : order)),
    );
  return (
    <AssistedPage
      name="Orders"
      instructions="Every order of the shop. Ship an order that is waiting to ship by its id."
      content={() => orders}
    >
      <ul className="flex flex-col gap-2">
        {orders.map((order) => (
          <li key={order.id} className="flex items-center gap-4">
            #{order.id} {order.customer}, {order.status}
            {order.status === "to ship" && (
              <AssistedAction
                name="ship_order"
                id={order.id}
                label={`Ship ${order.customer}'s order #${order.id}`}
              >
                <button className="rounded border px-2 py-1 text-sm" onClick={() => ship(order.id)}>
                  Ship
                </button>
              </AssistedAction>
            )}
          </li>
        ))}
      </ul>
    </AssistedPage>
  );
}
```

The panel's header now reads "On Orders". Ask "Which orders are waiting to ship?".

The assistant calls `get_page_content` first, and its answer names Acme's #1042 and Globex's #1043.

Ask "Ship Globex's order."

The assistant calls `ship_order` with the id `1043`, which presses Globex's **Ship** button. The row now reads "shipped", its button is gone, and the assistant tells you the order shipped.

## What you built

A Next.js app whose assistant runs on Super Assist. The project's agent answers, the Orders page introduces itself and lends its content on demand, and each row lends an action the agent presses by id.

Next:

- [Make an action consequential](https://superassist.app/how-to/make-an-action-consequential.md), so the user presses it or approves it.
- [Lend a form's fields](https://superassist.app/how-to/lend-form-fields.md), so the assistant fills them.
- [Add `go_to_page`](https://superassist.app/how-to/add-go-to-page.md) once the app has more than one page.
- [Place the panel](https://superassist.app/how-to/place-the-panel.md) as a sheet or embedded, and [rearrange its parts](https://superassist.app/how-to/rearrange-the-panel.md).
- [Mount the devtools](https://superassist.app/how-to/mount-devtools.md) to see what the page lends.
- [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md) to name your signed-in users, and to accept your production origin before you deploy.
- [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md), from the project and its agent to what the page lends.

---

# Agents and skills

> Create the agent that answers in your app, write its instructions, pick its model, and give it skills, databases and knowledge bases.

An agent is what answers in your app: its instructions, its model, and the skills, databases and knowledge bases it may use. Every member can chat with it in the dashboard, and a project's end users reach it through the panel. This page covers the **Agents** and **Skills** pages of the dashboard.

## Create an agent

On **Agents**, press **New agent**, or [install a template](https://superassist.app/dashboard/templates.md) to start from a finished one.

- **Name**: lowercase letters, numbers and hyphens, up to 64 characters. Spaces become hyphens.
- **Description**: one line shown in the agents list.
- **Instructions**: what the agent is for and how it behaves. They are a Liquid template filled in at every turn, so `{{ organization.name }}` prints your organization's name. **Start from a template**, beside the label, pastes one of three starters: General assistant, Customer support or Data analyst.
- **Provider** and **Model**: Vercel AI Gateway with its catalog, or Workers AI. **Thinking before each reply** applies to the Anthropic and OpenAI models the catalog tags as reasoning, and is ignored elsewhere.

Then add what the agent may use. It reads every database you add and writes only where **Allow writes** is on. It searches every knowledge base you add. Press **Create agent**.

### What the instructions can print

| Variable            | Prints                                     |
| ------------------- | ------------------------------------------ |
| `today`             | The date in UTC, like `Monday 2026-10-05`  |
| `agent.name`        | The agent's name, with `agent.description` |
| `organization.name` | Your organization's name                   |
| `skills`            | Each skill's `name` and `description`      |
| `databases`         | Each database's `name` and `writable`      |

A missing variable prints nothing. An instructions template that doesn't parse is refused, with the line that failed.

### What every agent already has

Four rules close every prompt, whatever the instructions say, so you don't write them: answer only from the instructions, the knowledge bases, the open page and tool results; one step at a time; claim an action done only when a tool call completed it; and say what a handoff or a consequential page action will do and wait for a yes. Every thread also has the `handoff` tool. See [Handoffs](https://superassist.app/dashboard/handoffs.md).

## Try the agent

The agent's page opens on **Chat**, the same panel your app shows, with your threads on the side. A member's test chat may pick another model and can fetch URLs, which an end user's thread can't. Test chats aren't counted in a project's conversations.

**Editor** holds the form above. On extra-large screens, **Configuration** lists the skills, databases, knowledge bases and rendered instructions beside the chat.

## Saving reaches running threads

Pressing **Save changes** sends the agent's configuration to every thread, members' and end users' alike. The model, tools, skills and thinking level apply from the next turn. Changed instructions arrive as a reminder on the thread's next message.

The configuration carries a copy of each skill's text, so a skill you edit reaches an agent on that agent's next save. Open the agent and press **Save changes** after editing its skills.

## Write a skill

A skill is a procedure every agent of the organization can read. The prompt lists each of the agent's skills by name and description on every turn; the agent loads a skill's instructions only when its description fits the request. So the description decides when the skill is used, and the instructions what it does.

On **Skills**, press **New skill**:

- **Name**: the same rule as an agent's.
- **What**, **Use when** and **Not for**: one sentence each. They save together as the skill's description, one labelled line each, up to 1024 characters. **Not for** keeps the agent from loading the skill on a request that only looks like a fit; name the neighbouring skill or the agent's own job there.
- **Instructions**: Markdown. Say when the skill applies, then the steps. Plain text, not Liquid.

Then add the skill to an agent on its editor's **Skills** group. Through the API, write the three lines into `description` yourself:

```text
What: Reviews a pull request against the team checklist.
Use when: Asked to review a pull request, a diff or a branch.
Not for: Writing the fix or reviewing a design doc.
```

The nine skills of the [SaaS support template](https://superassist.app/dashboard/templates.md) are worked examples.

## Databases

A database is the organization's own SQLite store. Create one on **Databases**, then shape its tables in the explorer or with the query API. An agent with a database gets two tools: one returns its schema, and one runs a single statement. A statement that writes to a database the agent may only read is rolled back. The Free plan includes 3 databases and the Pro plan 25.

---

# Knowledge bases

> Give an agent a help center or files to answer from, follow each source's runs, and see what it cites under the answer.

A knowledge base is a named body of content the agent searches while it answers: a crawled site, uploaded files, or both. Each one is made of sources, indexed on their own. Add a knowledge base to an agent and it searches the sources that are ready, answers from the passages it finds, and cites them under the answer.

## Create one and add sources

On **Knowledge**, press **New knowledge base**, name it, and press **Create knowledge base**. Then add sources on its page:

- **Add URL** crawls a public page and the pages under its path, such as a help center's home. Crawling starts at once.
- **Upload file** indexes one file as a source of its own. Plain text, code and markup up to 10 MiB; PDF, Office files, HTML, CSV and images up to 4 MiB. Images aren't read for text.

Each source shows **Indexing** with its progress, then **Ready** with its page count, or **Error** with the reason. The **Try a question** box on the knowledge base's page runs the same search the agents run, so you can check what it finds before an agent does.

### Crawl options

Set them when adding a URL, or later from the source's menu under **Edit crawl options**. Saving options doesn't crawl again; **Sync** the source afterwards.

| Option                 | Default              | What it does                                                  |
| ---------------------- | -------------------- | ------------------------------------------------------------- |
| **Page limit**         | 500                  | The most pages to index. 500 is also the cap.                 |
| **Link depth**         | Any                  | How many links to follow from the URL.                        |
| **Discovery**          | Sitemaps and links   | Where the crawl finds pages.                                  |
| **Include patterns**   | Under the URL's path | One per line. `*` matches within a path segment, `**` across. |
| **Exclude patterns**   | None                 | One per line. Matching pages are skipped.                     |
| **Render JavaScript**  | On                   | Needed for pages built in the browser. Off is faster.         |
| **Include subdomains** | Off                  | Also crawl the same path on the site's subdomains.            |

A site's Content Signals can refuse the crawl, which fails the run with that reason.

## Runs

Every sync is a run, shown newest first on the source's page with its stages: **Crawl**, **Store** and **Index** for a URL, **Upload** and **Index** for a file. A run lists every page it went through with **Indexed**, **Failed** and its reason, or **Not indexed**.

While a run goes, what the source indexed before stays searchable. When it finishes, unchanged pages are kept, changed pages are replaced, and pages the crawl no longer found are removed. **Cancel run** stops it and deletes nothing.

## Give it to an agent

Open the agent's editor, press **Add a knowledge base** under **Knowledge**, and save. The agent's prompt then names its knowledge bases and tells it to search them with `search_knowledge` before answering a question they may cover, to answer from the passages, and to cite no source the search didn't return.

A search returns up to 8 passages, each with its knowledge base, title, URL, score and text. The panel shows them under the answer as numbered chips, one per page or file, in the [sources card](https://superassist.app/components/cards/sources-card.md).

Deleting a knowledge base deletes its sources and their indexed content, so agents no longer find them.

---

# Templates

> Install a ready-made agent with its skills and databases in one step, replace its placeholders, and attach a knowledge base.

A template is a finished agent or skill, written as Markdown and bundled into Super Assist. Installing an agent template creates its databases with their tables, the agent, and each of its skills your organization doesn't already have by name. Your organization then owns copies it can edit. The templates themselves are public at [github.com/mertdogar/super-assist-templates](https://github.com/mertdogar/super-assist-templates).

## Install one

On **Agents**, press **Install a template** and pick one. The agent opens when it's installed.

The install reuses a skill of the same name, so installing a second template that shares a skill, or installing twice, keeps the skill you may have edited. An agent or database that already has the template's name stops the install, as does a plan limit.

## The SaaS support agent

`saas-support` supports the customers of a SaaS product from your help center, with sources. It works through problems, billing, cancellations, leads and feature requests, does or explains tasks on the open page, and hands off to your team when a person is needed.

| Skill                        | Does                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `grounded-answer`            | Answers a product question from the passages a knowledge base search returns   |
| `troubleshooting`            | Works through a problem one fix at a time, checking each result                |
| `billing-and-account`        | Answers plan and invoice questions and opens the billing page for changes      |
| `cancel-or-pause`            | Makes one retention offer, then cancels or pauses through the page or a person |
| `lead-capture`               | Takes down a prospective buyer's contact and interest for sales                |
| `feature-request`            | Records a request for something the product doesn't do yet                     |
| `guide-me-through-this-page` | Teaches the open page one field or action at a time                            |
| `do-it-for-me`               | Fills the open page's fields and presses its actions, after a yes              |
| `escalate-to-human`          | Hands the thread to a person with the `handoff` tool, after asking             |

Its `captures` database holds a `lead` table and a `featureRequest` table. The two capture skills write to the page's form when the open page lends one, otherwise to these tables.

## Before you go live

The agent's instructions open with a note, in a Liquid comment the model never sees, listing the placeholders to replace in its skills:

- `[support hours]` in `escalate-to-human`: when your team replies to handoffs.
- `[billing page]` in `billing-and-account` and `cancel-or-pause`: where customers change their plan.
- `[plan names]` in `billing-and-account`: your plans' names.
- `[retention offer]` in `cancel-or-pause`: your one offer to a customer who wants to cancel.

Then:

1. Edit each skill on **Skills** and replace its placeholders.
2. Open the agent, press **Add a knowledge base** under **Knowledge**, and pick your help center. See [Knowledge bases](https://superassist.app/dashboard/knowledge-bases.md).
3. Press **Save changes** on the agent, so its threads get the edited skills.
4. Set **Support email** in **Settings**, so handoff alerts reach your team.

## What every template relies on

The agent's prompt already carries the core rules, the `handoff` tool, the knowledge base search and the page's lent tools, so the templates say only what is specific to them. [Agents and skills](https://superassist.app/dashboard/agents-and-skills.md) describes each.

---

# Handoffs

> What happens when an agent hands a conversation to a person, how the end user's panel shows it, and how a member reads the thread, replies and closes it.

A handoff is an agent passing a thread to a person at your organization. The person is alerted by email, reads the thread from the **Inbox**, and replies into it. The end user sees the reply in the panel, in the same thread, without a reload. The agent stays out of the thread until a member closes the handoff.

## How it starts

Every thread of every agent has the `handoff` tool. The agent calls it when the end user asks for a person or it can't help further, with a one-line reason, a summary of what the user needs and what was tried, and the user's contact when they gave one. The core rules make the agent say what the handoff does and wait for a yes first, and the `escalate-to-human` skill of the [SaaS support template](https://superassist.app/dashboard/templates.md) asks for an email on the way.

The agent isn't the only one watching. After each reply, a decision model reads the exchange and judges whether a person should take over: the end user asked for one, is frustrated or repeating themselves, asked for something outside the agent's purpose, or the agent couldn't answer. When it looks that way, the panel shows a **Talk to a person** button under the messages, which sends "I'd like to talk to a person." and the agent hands off. When the end user plainly asked for a person, the handoff opens at once with the reason "The user asked for a person", with no further turn. See [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md#after-the-reply-a-decision-model-reads-the-exchange).

The handoff opens, and an email goes to the organization's **Support email** from **Settings**, or to the owner when none is set. Its subject names the agent and the reason, and its button opens the handoff in the dashboard.

## What the end user sees

Under the panel's composer, the thread reads **A person will reply here.** The end user can keep writing; the messages are kept for the person, and the agent doesn't answer them. Once a member has replied, the note reads **You're talking with <name>.**, and each reply shows as that person's message under their name.

## Reply and close

**Inbox** in the sidebar holds the open handoffs under **Unassigned**, **Mine** and **Teammates**, and those closed today; **All closed** lists every closed handoff. Open one to read the whole thread, with the end user, the agent and each member named. Press **Claim** to take an unassigned handoff. The select beside **Close handoff** shows who holds it; pick another member, or **Unassigned**, to pass it on.

1. Write in **Reply to the end user in this thread** and press **Send reply**. The reply lands in the thread at once.
2. When the person's part is done, press **Close handoff**. The note under the composer goes away, and the agent answers the thread's next message again.

A closed handoff stays under **All closed** for the record.

---

# Journeys

> Walk end users through your app toward a goal, one step at a time: write a journey from your pages, choose what starts it, publish it, try it in your app, and read how far end users get.

A journey is an ordered set of up to ten steps that walks end users through your app toward a goal, such as creating their first order. Each step opens a page of your app, points at an action or field that page lends, and shows a title and a line or two of text beside it. End users see nothing of a journey until a member publishes it.

Journeys live under a project. Open the project and choose the **Journeys** tab. The list shows each journey by its goal with its name under it, whether it is a draft, published, or published with unpublished changes, what starts it, a bar per published step for the share of end users who reached it, and how many end users started and completed it over the last 30 days. A step that points at something the page catalog hasn't seen shows its warning in amber under the goal.

## Write one

Press **New journey**, or **New journey from this page** on a page of the **Pages** tab to start with a step there. The journey's goal is its title. On the **Steps** tab, the steps run left to right after a **Start** card, each drawn as the card end users see, with its page and what it points at above it. Select a card to edit it in the panel below. There is no Save button: the journey saves as you type, and a line under the buttons shows while it saves, or what it still needs. A new journey is saved once it has a name, a goal and one step with a title.

On **Start**:

- **Name**: lowercase letters, numbers and hyphens, unique in the project. Your code and links start the journey by this name.
- **Goal**: what the journey is for, in a sentence. Your team and coding agent read it; end users never do.
- **Starts**: what starts it by itself. See [What starts a journey](#what-starts-a-journey).

Press **Add step**, then pick for the step:

- **Points at**: a page from the project's page catalog, the assisted pages your app has shown or your coding agent posted, and an action or field it lends or the page itself. The list groups the catalog by page; open a page to choose, or search pages, actions and fields by name. An action step passes when the end user presses it, a field step when they change it and move on, and a step on the page itself when they press **Next**. Every step also offers **Next**, which reads **Done** on the last.
- **Title** and **Body**: the words shown beside the step.

A step on a page with an `:id` in its path, such as `/orders/:id`, never opens that page by itself. It shows once the end user has one open, usually from the step before. A name lent by every row of a list points at the first row.

Each card's menu moves the step earlier or later, or deletes it. Once the journey is published, the arrows between the cards show how many end users reached each step.

The project's **Pages** tab lists the catalog. Select a page to see its instructions, the actions and fields it lends, when each was last seen, and which journey steps point at each one.

### Steps the catalog hasn't seen

A step shows in amber when the page catalog has no such page, the page doesn't lend that action or field, or the catalog hasn't seen it for 30 days. Playback waits five seconds for what a step points at, then skips the step and counts it as missed. The warning doesn't stop you publishing, since a page reports what it lends only once your app shows it.

## What starts a journey

- **When an end user opens** the first step's page: the journey starts by itself the first time an end user is shown that page, once per end user. A journey they finished or closed never starts by itself again, and one they left halfway resumes where they were. If two journeys match, the older one plays first.
- **Only from your code or a link**: nothing starts it by itself.

Either way, your code can start it with `startJourney("<name>")` from `useAssisted()`, and a link can with `?journey=<name>` on any page of your app. Both start it from the first step, even for an end user who already finished it.

## Publish

End users see the published copy only. **Publish** copies the steps and what starts the journey to the published copy, and the badge then reads **Published** with when. After that, edits change the draft alone, the badge reads **Unpublished changes**, and **Publish changes** appears. A rename or a new goal applies at once.

The menu at the end of the buttons holds:

- **Discard changes**: while there are unpublished changes, puts the steps and the trigger back to the published copy.
- **Delete journey**: deletes it with its funnel and every end user's progress, after you confirm.

Your coding agent can draft journeys through the API for you to review, signed in as you on the MCP server or with an organization key; see [Set up through the API](https://superassist.app/how-to/set-up-through-the-api.md#draft-journeys). Only a member can publish one, so an organization key can't.

## Try in app

**Try in app** opens your app with `?journey=<name>` on the project's first allowed origin that isn't a wildcard, and its menu lists the others. It plays the published copy, so it waits for the first publish, and unpublished changes don't show until you publish them. Its runs count in the funnel like anyone else's.

## The funnel

The **Results** tab shows how end users who started the published journey over the last 7 or 30 days got on:

- **Started**, **Completed**, **Dismissed** and **In progress**, each a count of end users.
- One bar per published step, split into those who passed it, those on it now, those who missed it because playback couldn't find what it points at, and those who closed the journey there.
- The latest end users with where each one is, the steps they missed, and when they started and were last active.

The funnel counts by step number against the published copy, so a step you moved in an unpublished draft keeps its old numbers until you publish.

---

# Confirm card

> The card that asks the user before a consequential action or tool goes ahead, and stays as a receipt.

The confirm card asks the user in the conversation before an action with `consequential="confirm"`, or a tool with `consequential: true`, goes ahead. After the answer it stays as a receipt.

![The sheet panel on Orders. The assistant says cancelling Globex's order #1043 needs approval, and a card below reads Cancel Globex's order #1043 with Approve and Deny.](https://superassist.app/_astro/confirm-light.D_9uN-ch.webp)

## Usage

The card shows for every consequential action or tool. From `examples/app/app/orders/page.tsx`:

{/* prettier-ignore */}
```tsx
<AssistedAction
  name="cancel_order"
  id={order.id}
  label={`Cancel ${order.customer}'s order #${order.id}`}
  consequential="confirm"
>
  <Button
    size="sm"
    variant="outline"
    onClick={() => shop.call("cancelOrder", [order.id])}
  >
    Cancel
  </Button>
</AssistedAction>
```

## What the model sees

The action's entry ends with ` (asks first)`, so the model calls it and lets the panel ask. While the card waits, the call has no answer. The card's title is the picked row's label, `Cancel Globex's order #1043`. For a tool it is `question(args)`, or the tool's description without one.

## States

### Approved

![After Approve: the card reads Finished and order 1043 reads cancelled.](https://superassist.app/_astro/confirm-approved-light.Vcbk-W5a.webp)

Approve checks the element again and presses it. The card reads "Approved, running", then "Finished". The call answers `Approved by the user and pressed "Cancel Globex's order #1043".` with the Orders note.

### Declined

![After Deny: the card reads Denied and order 1043 still waits to ship with its Ship and Cancel buttons.](https://superassist.app/_astro/action-declined-light.BgwLPTqK.webp)

Deny presses nothing, and the card reads "Denied". The call answers `The user declined "Cancel Globex's order #1043". That is final: leave it unless they ask for it again.`

When the press fails after approval, the card reads "Didn't go through".

## Props

None. The package renders it for each consequential action or tool, inline in the conversation. Replace it for every one with `cards.confirm` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). A tool's own `render` replaces it for that tool. The card carries `data-slot="approval-card"`.

## See also

- [Make an action consequential](https://superassist.app/how-to/make-an-action-consequential.md).
- [Why consequential actions ring](https://superassist.app/explanation/consequential-actions.md).

---

# Choices card

> The card that asks the user a question with two to four answers they pick with one click.

The choices card shows the question an `offer_choices` call asks, with two to four answers the user picks with one click. The pick is the call's answer.

![The sheet panel on Orders. A card asks Which orders should I show? with To ship, Shipped, Cancelled and All.](https://superassist.app/_astro/choices-light.ohFUG0wq.webp)

## Usage

`AssistedProvider` lends `offer_choices` on every page. There is nothing to set up.

## What the model sees

`offer_choices` is described as:

```txt wrap
Ask the user a question with two to four short answers they pick with one click, and answer with their pick.
```

It takes `question`, a string, and `options`, two to four strings. The call waits for the pick.

## States

### Picked

![The same card after the user picked To ship: only To ship remains, with a check.](https://superassist.app/_astro/choices-picked-light.Boz4Drmf.webp)

The pick answers the call with `The user picked "To ship".` The card stays in the conversation, showing only the pick with a check.

## Props

None. The package renders it in place of the `offer_choices` call. Replace it with `cards.choices` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). The card carries `data-slot="assisted-choices"`.

## See also

- [Model context](https://superassist.app/reference/model-context.md#built-in-tools) lists every built-in tool.

---

# Links card

> The card that shows the pages show_links offers to open, each with a title and a gist.

The links card shows the pages a `show_links` call offers, each with a title and a one-line gist. A click opens the page through the provider's `navigate`.

![The floating panel on Dashboard. The user asked what needs attention, and the links card offers Umbrella's order #1044, waiting to ship, and Globex's order #1046, its refund open.](https://superassist.app/_astro/links-light.BgF5NE1-.webp)

## Usage

`AssistedProvider` lends `show_links` when it has `destinations` and `navigate`, as in [Add `go_to_page`](https://superassist.app/how-to/add-go-to-page.md).

## What the model sees

`show_links` is described as:

```txt wrap
Show the user links to pages of the app, the pages go_to_page opens, each with a title and a one-line gist. A click opens the page.
```

It takes `items`, one or more of `{ to, id?, title, gist? }`, where `to` is a destination's name and `id` fills its `:id`. The call in the screenshot answered:

```txt wrap
Showed the user links to Umbrella's order #1044, Globex's order #1046.
```

An unknown page or a missing id answers with an error, and the card stays hidden.

## Props

None. The package renders it in place of the `show_links` call. Each link is an `a` with the page's path as its `href`. Replace it with `cards.links` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). The card carries `data-slot="assisted-links"`.

## See also

- [Add `go_to_page`](https://superassist.app/how-to/add-go-to-page.md) sets the destinations both tools use.

---

# Table card

> The card show_table renders, records of one kind as rows and the fields they share as columns.

The table card lays out records of one kind: rows of the same shape, with the fields they share as columns. The assistant shows it with `show_table` when the user asks to see data laid out.

![The sheet panel on Orders. The user asked for the open orders as a table, and a table titled Orders waiting to ship lists Acme, Globex and Umbrella with their totals.](https://superassist.app/_astro/table-light.B2jqtMVp.webp)

## Usage

`AssistedProvider` lends `show_table` on every page. There is nothing to set up. See [Show a table, a spec or a comparison](https://superassist.app/how-to/show-structured-answers.md).

## What the model sees

`show_table` is described as:

```txt wrap
Show the user a table: records of the same kind as rows, the fields they share as columns. For structured answers the user can scan, like a list of orders.
```

| Parameter | Type                                                                                       | Required |
| --------- | ------------------------------------------------------------------------------------------ | -------- |
| `title`   | `string`                                                                                   | No       |
| `columns` | One or more of `{ key: string; label: string }`                                            | Yes      |
| `rows`    | `Record<string, string \| number \| boolean \| null>[]`, each a row's values by column key | Yes      |

The call answers `Showed the user a table.` It changes nothing on the page.

## Props

None. The package renders it in place of the `show_table` call: the title, then the table with the title as its caption. Replace it with `cards.table` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). The card carries `data-slot="assisted-table"`.

## See also

- [Spec card](https://superassist.app/components/cards/spec-card.md) for one thing's properties.
- [Comparison card](https://superassist.app/components/cards/comparison-card.md) for two or three options side by side.

---

# Spec card

> The card show_spec renders, one thing's properties as label and value rows.

The spec card lays out one thing's properties as label and value rows, like an order's details or a page's settings. The assistant shows it with `show_spec` when the user asks to see data laid out.

![The sheet panel on Settings. The user asked for the settings as a sheet, and a spec card titled Shop settings lists the shop name, currency and notification email.](https://superassist.app/_astro/spec-light.-tLn59or.webp)

## Usage

`AssistedProvider` lends `show_spec` on every page. There is nothing to set up. See [Show a table, a spec or a comparison](https://superassist.app/how-to/show-structured-answers.md).

## What the model sees

`show_spec` is described as:

```txt wrap
Show the user a spec sheet: one thing's properties as label and value rows. For structured answers the user can scan, like an order's details or a page's settings.
```

| Parameter | Type                                              | Required |
| --------- | ------------------------------------------------- | -------- |
| `title`   | `string`                                          | Yes      |
| `rows`    | One or more of `{ label: string; value: string }` | Yes      |

The call answers `Showed the user a spec sheet.` It changes nothing on the page.

## Props

None. The package renders it in place of the `show_spec` call, every row shown. Replace it with `cards.spec` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). The card carries `data-slot="spec-sheet"`.

## See also

- [Table card](https://superassist.app/components/cards/table-card.md) for several records of one kind.

---

# Comparison card

> The card show_comparison renders, two or three options side by side on the same traits, with the one the assistant recommends.

The comparison card puts two or three options side by side on the same traits, marks the one the assistant recommends, and says why. The assistant shows it with `show_comparison` when the user asks to compare.

![The sheet panel on Orders. The user asked to compare orders 1042 and 1043, and a comparison card shows both on customer, items, total and status, recommending Acme's order.](https://superassist.app/_astro/comparison-light.DGRLfLrG.webp)

## Usage

`AssistedProvider` lends `show_comparison` on every page. There is nothing to set up. See [Show a table, a spec or a comparison](https://superassist.app/how-to/show-structured-answers.md).

## What the model sees

`show_comparison` is described as:

```txt wrap
Show the user two or three options side by side on the same traits, with the one you recommend and why. For structured answers the user can scan, like comparing two orders.
```

| Parameter     | Type                                                                                                                        | Required |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- | -------- |
| `traits`      | One or more strings, the traits' names                                                                                      | Yes      |
| `options`     | Two or three of `{ name: string; headline: string; traits: string[] }`, `traits` the option's value for each trait in order | Yes      |
| `recommended` | `string`, the name of the recommended option                                                                                | Yes      |
| `reason`      | `string`, one sentence on why                                                                                               | Yes      |

The call answers `Showed the user a comparison.` It changes nothing on the page.

## Props

None. The package renders it in place of the `show_comparison` call. Replace it with `cards.comparison` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). The card carries `data-slot="comparison-card"`.

## See also

- [Table card](https://superassist.app/components/cards/table-card.md) for more than three records.

---

# Sources card

> The card under an answer that cites the knowledge base passages the agent's searches found, one numbered chip per source.

The sources card cites what the agent read in its knowledge bases. It sits under the assistant's answer as a row of numbered chips, one per source, and a click on a chip opens its passages with the source's title, domain and knowledge base. A web page's chip has a link icon and an Open link; a file's chip has a document icon and no link.

## Usage

There is nothing to set up. The card shows for the `search_knowledge` calls of an agent with knowledge bases on Super Assist. The search runs on the server, so the package lends no tool for it; it only renders the calls.

## What the card shows

Every `search_knowledge` call of a message goes into one card, after the message's last text. Passages of the same page, or of the same file, become one chip, in the order the searches returned them. While a search runs, the card is a skeleton row in the same place.

Each call answers the model with its passages, best match first:

```ts
type Answer = {
  passages: {
    knowledgeBase: string;
    title: string; // a web page's title, or a file's name
    url: string | null; // a web page's address; a file has none
    score: number; // from 0 to 1
    text: string;
  }[];
};
```

The agent's prompt asks it to answer from the passages and to cite no source the search did not return, so the chips match the answer.

## Props

None. The package renders it under the answer. Replace it with `cards.sources` on `AssistedProvider`, see [Swap a card](https://superassist.app/how-to/swap-a-card.md). Your card gets the last call's props, with `result.passages` holding every call's passages and `status` running while any call runs. The card carries `data-slot="sources"`.

`Sources` renders the same chips from a `passages` array and a `searching` flag, for a card of your own.

## See also

- [Links card](https://superassist.app/components/cards/links-card.md) for pages of the app to open.

---

# AssistedProvider

> Wraps the app in the runtime and lends what every page shares, with the cards that show its tools. With useAssisted.

`AssistedProvider` lends what every page shares: the universal instructions, `offer_choices`, the show tools `show_table`, `show_spec` and `show_comparison`, and `go_to_page` and `show_links` when it has destinations. It holds the cards those tools render. `useAssisted` reads and drives the panel's open state.

![The floating panel, headed On Orders. The user asked to go to the orders, and the expanded go_to_page call answers with Opened /orders and the Orders page's note.](https://superassist.app/_astro/provider-light.87KslKZ5.webp)

## Usage

Give it the runtime from `useAssistedRuntime` and wrap the app. From `examples/app/app/assistant.tsx`:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  host: process.env.NEXT_PUBLIC_SUPER_ASSIST_HOST,
});

<AssistedProvider
  runtime={runtime}
  destinations={destinations}
  starters={["What can you do on this page?"]}
  navigate={(path) => router.push(withMode(path))}
>
  <Layout>{children}</Layout>
</AssistedProvider>;
```

`destinations` names the pages `go_to_page` opens. From the same file:

```ts
const destinations = {
  home: "/",
  orders: "/orders",
  order: "/orders/:id",
  customers: "/customers",
  settings: "/settings",
};
```

## What the model sees

Every request's system text holds the universal instructions, quoted in [Model context](https://superassist.app/reference/model-context.md#universal-instructions). With the example's destinations, `go_to_page` is described as:

```txt wrap
Open a page of the app for the user and answer, once it has loaded, with the page section of the page it opened. The pages and their paths: home /, orders /orders, order /orders/:id, customers /customers, settings /settings.
```

The call in the screenshot answered with the path it opened and the note of the page there:

```md wrap
Opened /orders.

## The page the user has open: Orders

Every order of the shop, as filtered by status with filter_orders, and charted by status with chart_orders. Ship or cancel an order that is waiting to ship by its id. New order opens a dialog that introduces itself. Each order has a page of its own with its note and refund.

Its tools: filter_orders, chart_orders, get_page_content.

Its actions: cancel_order, new_order, ship_order.
```

`show_links`, `offer_choices` and the show tools render cards, each on its own page under [Cards](https://superassist.app/components.md#cards).

## Props

| Prop                      | Type                        | Required | Description                                                         |
| ------------------------- | --------------------------- | -------- | ------------------------------------------------------------------- |
| `runtime`                 | `AssistantRuntime`          | Yes      | The runtime from `useAssistedRuntime`.                              |
| `destinations`            | `Record<string, string>`    | No       | Page names to paths. `:id` in a path takes an id.                   |
| `destinationsDescription` | `string`                    | No       | Replaces the pages and their paths in `go_to_page`'s description.   |
| `navigate`                | `(path: string) => unknown` | No       | Opens a path. `go_to_page` awaits it.                               |
| `starters`                | `string[]`                  | No       | First messages the empty state suggests on a page without its own.  |
| `cards`                   | `AssistedCards`             | No       | Cards that replace the package's, by tool. See below.               |
| `trace`                   | `boolean`                   | No       | Shows every press and fill on the page with a ring. Off by default. |
| `children`                | `ReactNode`                 | Yes      | The app.                                                            |

- Renders `AssistantRuntimeProvider` with `runtime`.
- Lends the universal instructions, `offer_choices`, `show_table`, `show_spec` and `show_comparison`.
- Lends `go_to_page` and `show_links` only when both `destinations` and `navigate` are given.
- Renders the agent's `search_knowledge` calls as the sources card under the answer, without lending a tool.
- Answers calls to tools and actions that have left with `{ error }` and the open page's note.
- Stamps each user message with the id of the tab that sent it, in `metadata.custom.tab`, and runs a call only in that tab. Other tabs wait for its result.
- Holds the panel's open state, closed at first.
- With `trace`, a press or fill flashes a ring on its element for a second, and a `"confirm"` action keeps the ring on its element while the panel asks. An action or field sets its own `trace` to differ.
- `AssistedPage`, `AssistedAction`, `AssistedInput`, `AssistedField`, `useAssistedTool`, `useAssisted`, the panel and the devtools render inside it.

## AssistedCards

`cards` maps a card to the component that replaces it. Each is optional, and each takes the default card's props: the tool call's `args`, `result`, `isError`, and while it waits, `interrupt` and `resume`.

| Key          | Replaces                                                                                   | `args`                                              |
| ------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `confirm`    | The [confirm card](https://superassist.app/components/cards/confirm-card.md) of every consequential action and tool | Any. `interrupt.payload` is `{ name, label, id? }`. |
| `choices`    | The [choices card](https://superassist.app/components/cards/choices-card.md)                                        | `{ question, options }`                             |
| `links`      | The [links card](https://superassist.app/components/cards/links-card.md)                                            | `{ items }`                                         |
| `table`      | The [table card](https://superassist.app/components/cards/table-card.md)                                            | `{ title?, columns, rows }`                         |
| `spec`       | The [spec card](https://superassist.app/components/cards/spec-card.md)                                              | `{ title, rows }`                                   |
| `comparison` | The [comparison card](https://superassist.app/components/cards/comparison-card.md)                                  | `{ traits, options, recommended, reason }`          |
| `sources`    | The [sources card](https://superassist.app/components/cards/sources-card.md) under an answer                        | `{ query, knowledgeBase? }`                         |

A `confirm` card answers with `resume({ approved: boolean })`, and a `choices` card with `resume(option)`.

## useAssisted

```ts
useAssisted(): {
  isOpen: boolean;
  open: (message?: string) => void;
  close: () => void;
  page: string | undefined;
}
```

| Field            | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `isOpen`         | Whether the floating or sheet panel is open.                             |
| `open(message?)` | Opens the panel. With a message, appends it to the thread as the user's. |
| `close()`        | Closes the panel.                                                        |
| `page`           | The open assisted page's name, or `undefined`.                           |

Throws `Render this inside an AssistedProvider` outside the provider. The panel's header reads `page`, and [`AssistedPanel.Trigger`](https://superassist.app/components/panel/roots-and-window.md#leaf-props) toggles `isOpen`.

## See also

- [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md) for the options of the runtime it takes.
- [Swap a card](https://superassist.app/how-to/swap-a-card.md) sets `cards`.
- [Add `go_to_page`](https://superassist.app/how-to/add-go-to-page.md) sets `destinations` and `navigate`.
- [How model context composes](https://superassist.app/explanation/model-context.md) explains what it lends and when.

---

# AssistedPage

> Introduces a page, or a dialog over it, to the assistant, with its name, its instructions and its content on demand.

`AssistedPage` lends a page's note, its name and instructions in every request, and `get_page_content`, which answers with what the page shows when the assistant asks.

![Order #1045 beside the sheet panel, headed On Order #1045. The expanded get_page_content call answers with the order as JSON.](https://superassist.app/_astro/page-light.BSzSPTWX.webp)

## Usage

Wrap the page's content. From `examples/app/app/orders/[id]/page.tsx`:

```tsx
<AssistedPage
  name={`Order #${id}`}
  instructions="One order: its customer, items, total, status, refund and note. note fills the note field without saving it, and save_note saves what the field holds."
  content={() => (row ? { ...row, note: order!.note, noteField: draft } : `No order #${id}.`)}
>
  {order && row ? (
    <OrderDetails order={order} row={row} draft={draft} setDraft={setDraft} />
  ) : (
    <p className="text-sm text-muted-foreground">No order #{id}.</p>
  )}
</AssistedPage>
```

## What the model sees

The open page's note, read when a message is sent. Order #1045's:

```md wrap
## The page the user has open: Order #1045

One order: its customer, items, total, status, refund and note. note fills the note field without saving it, and save_note saves what the field holds.

Its tools: get_page_content.

Its actions: refund_order, save_note.

Its fields: note: The order's note, now "".
```

The note never holds the content. `get_page_content` is described as:

```txt wrap
What the page the user has open shows right now. Call it first for anything about this page.
```

It answers with `content` as it is at the call, as the screenshot shows.

## States

### A dialog over the page

![The New order dialog over Orders beside the sheet panel, now headed On New order. The expanded new_order call answers with the dialog's note.](https://superassist.app/_astro/page-dialog-light.Du--s8gq.webp)

The New order dialog is an `AssistedPage` of its own. Mounted last, it is the page the user has open: the header reads On New order, and pressing `new_order` answered with the dialog's note.

```md wrap
Pressed "Open the New order dialog".

## The page the user has open: New order

A dialog over Orders for a new order. Fill its fields with order_field by id, then save_order creates the order and closes the dialog; cancel closes it without saving.

Its tools: get_page_content.

Its actions: cancel, save_order.

Its fields: order_field (customer: Customer, now ""; product: Product, now ""; quantity: Quantity, now "1"; note: Note, now "").
```

When the dialog closes, Orders is the open page again.

## Props

| Prop           | Type                         | Required | Description                                                                        |
| -------------- | ---------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `name`         | `string \| (() => string)`   | Yes      | The page's name.                                                                   |
| `instructions` | `string \| (() => string)`   | Yes      | How to work on the page.                                                           |
| `content`      | `unknown \| (() => unknown)` | No       | What the page shows. Read when `get_page_content` is called.                       |
| `starters`     | `string[]`                   | No       | First messages the panel's empty state suggests on this page. Over the provider's. |
| `children`     | `ReactNode`                  | No       | The page. Tools, actions and fields under it belong to it.                         |

- The page the user has open is the last mounted `AssistedPage`, ordered by first render.
- Only the open page lends its note and `get_page_content`. The note is read at send time.
- `get_page_content` is lent only when `content` is given.
- A function prop is read each time it is needed, so it sees current state.
- `useAssistedTool` calls under the page are its tools. `AssistedAction` elements under it are its actions. `AssistedInput` and `AssistedField` elements under it are its fields. All leave when it unmounts.
- A page under the open one keeps its tools, actions and fields lent, but no note names them.

## See also

- [Make a page assisted](https://superassist.app/how-to/make-a-page-assisted.md), dialogs included.
- [Why content is read on demand](https://superassist.app/explanation/content-on-demand.md).
- [Model context](https://superassist.app/reference/model-context.md#the-page-note) gives the note's template.

---

# AssistedAction

> Lends an element of an assisted page as an action the assistant presses, rings or asks about. With useAssistedAction, ring and useRing.

`AssistedAction` lends one element of an assisted page as an action: the assistant presses it, or, when it is consequential, rings it for the user or asks in the panel first. `useAssistedAction` is the hook behind it, and `ring` and `useRing` point at any element.

![Orders beside the sheet panel. The user asked to ship Globex's order; the expanded ship_order call answers Pressed Ship Globex's order #1043 with the Orders note, and the third row now reads shipped.](https://superassist.app/_astro/action-light.CSV_i4_y.webp)

## Usage

Give each row the same `name` and its own `id`. From `examples/app/app/orders/page.tsx`:

```tsx
<AssistedAction
  name="ship_order"
  id={order.id}
  label={`Ship ${order.customer}'s order #${order.id}`}
>
  <Button size="sm" onClick={() => shop.call("shipOrder", [order.id])}>
    Ship
  </Button>
</AssistedAction>
```

## What the model sees

Same-name actions on a page are one tool that picks a row by `id`. With the shop's seed data, `ship_order` is described as:

```txt wrap
Press one of these by its id. 1042: Ship Acme's order #1042; 1043: Ship Globex's order #1043; 1044: Ship Umbrella's order #1044
```

It takes `{ id }`, an enum of `1042`, `1043` and `1044`, and the Orders note lists it under `Its actions:`. A consequential action carries a marker. `cancel_order`, with `consequential="confirm"`:

```txt wrap
Press one of these by its id. 1042: Cancel Acme's order #1042 (asks first); 1043: Cancel Globex's order #1043 (asks first); 1044: Cancel Umbrella's order #1044 (asks first)
```

`refund_order` on an order's page, with `consequential`:

```txt wrap
Refund this order (consequential)
```

The press in the screenshot answered with its label and the page as the press left it:

```md wrap
Pressed "Ship Globex's order #1043".

## The page the user has open: Orders
```

The Orders note follows in full. Every answer is listed in [Model context](https://superassist.app/reference/model-context.md#action-answers).

## States

### Rung

![Order #1045 with a ring around the Refund button and the label Refund this order above it. The panel says the Refund button is ready for the user.](https://superassist.app/_astro/action-rung-light.DZgB06tU.webp)

With `consequential`, a call rings the element and presses nothing. It answers `Rang "Refund this order" for the user; pressing it is theirs.`

### Asking

![Orders beside the sheet panel. Under the assistant's sentence, a card reads Cancel Globex's order #1043 with Approve and Deny.](https://superassist.app/_astro/action-confirm-light.BLflgrFi.webp)

With `consequential="confirm"`, a call asks in the panel with the picked row's label. The [Confirm card](https://superassist.app/components/cards/confirm-card.md) shows the question, and nothing is pressed while it waits.

### Declined

![The same view after Deny: the card reads Denied and order 1043 still waits to ship with its Ship and Cancel buttons.](https://superassist.app/_astro/action-declined-light.BgwLPTqK.webp)

Deny presses nothing, and the card stays as a receipt that reads Denied. The call answers `The user declined "Cancel Globex's order #1043". That is final: leave it unless they ask for it again.`

### Disabled

![Order #1045 with Save note disabled. The expanded save_note call answers with an error saying Save the note is disabled right now.](https://superassist.app/_astro/action-disabled-light.BgHMGFS0.webp)

A disabled element is not clicked. The call answers `{ error: '"Save the note" is disabled right now.' }`.

## Props

| Prop            | Type                   | Required | Description                                                                         |
| --------------- | ---------------------- | -------- | ----------------------------------------------------------------------------------- |
| `name`          | `string`               | Yes      | The action's name. Same-name actions on one page are one tool.                      |
| `label`         | `string`               | Yes      | What pressing does. Becomes the tool's description, or one entry of it.             |
| `id`            | `string`               | No       | The row's id within a same-name group.                                              |
| `consequential` | `boolean \| "confirm"` | No       | `true` rings the element for the user. `"confirm"` asks in the panel, then presses. |
| `trace`         | `boolean`              | No       | Shows the press on the page with a ring. Defaults to the provider's `trace`.        |
| `children`      | `ReactElement`         | Yes      | One element whose `ref` reaches a DOM element. Its own `ref` is kept.               |

- Throws `Render an assisted action inside an AssistedPage` outside a page.
- Without ids, the tool's description is the label with its marker, and it takes no parameters.
- With ids, the tool takes `{ id }` with an enum of the mounted rows' ids. Its description reads `Press one of these by its id.` followed by `<id>: <label>` pairs.
- A press waits for pending React updates to commit, then checks the element. Missing or disabled, it answers with an error and clicks nothing.
- `consequential` rings the element and answers that pressing is the user's.
- `consequential="confirm"` asks in the panel, checks the element again on approval, then clicks and answers `Approved by the user and pressed "<label>".` with the page's note. A denial answers with the decline text.
- A click answers `Pressed "<label>".` with the note of the page as the press left it, after the page changes or 300 ms.
- With `trace`, a click flashes a ring on the element, gone after a second or with the element. `"confirm"` rings the element while the panel asks, and the ring leaves with the answer.

## useAssistedAction

```ts
useAssistedAction<T extends HTMLElement = HTMLElement>(options: AssistedActionOptions): RefObject<T | null>
```

The hook behind `AssistedAction`. `AssistedActionOptions` is `{ name, label, id?, consequential?, trace? }`, as in the table above. Attach the returned ref to the element to press. Throws outside an `AssistedPage`.

## ring

```ts
ring(target: HTMLElement, options?: RingOptions): () => void
```

Points at one element, as in the Rung state. Returns a function that dismisses the ring.

| `RingOptions` field | Type      | Default                       | Description                                     |
| ------------------- | --------- | ----------------------------- | ----------------------------------------------- |
| `message`           | `string`  | `"The assistant points here"` | The word from the assistant beside the ring.    |
| `flash`             | `boolean` | `false`                       | Leaves on its own after a second, pulsing once. |

- One ring at a time. A new ring dismisses the open one.
- Scrolls the target to the center of the view, smoothly unless the user prefers reduced motion.
- Draws an outline 8 px outside the target that follows it as it moves, and pulses twice. Under reduced motion it fades once.
- Shows the message above the target, or below when there is no room. The message has `role="status"`.
- Dismissed by Escape, by any pointer down, by the target leaving the document, or by the returned function.
- A `flash` is also dismissed a second after it opens. `trace` on the provider flashes presses and fills this way.
- Sits at z-index 40. Colors come from `--primary` and `--primary-foreground`, with `#2563eb` and `#fff` as fallbacks.

## useRing

```ts
useRing(): (target: HTMLElement, options?: RingOptions) => () => void
```

`ring` for a component. Dismisses the ring it opened when the component unmounts.

## See also

- [Add actions and group row actions](https://superassist.app/how-to/add-actions.md).
- [Make an action consequential](https://superassist.app/how-to/make-an-action-consequential.md).
- [Why consequential actions ring](https://superassist.app/explanation/consequential-actions.md).

---

# AssistedInput

> Lends an input, textarea, native select, checkbox or switch as a field the assistant fills. With useAssistedInput.

`AssistedInput` lends one form field of an assisted page as a field the assistant fills as the user would type into it, and shows what it says now in the page's note. `useAssistedInput` is the hook behind it.

![Settings beside the sheet panel. The expanded setting call answers Filled Shop name; it now says Northwind Traders, and the Shop name field shows Northwind Traders, not yet saved.](https://superassist.app/_astro/input-light.CqDsk3hW.webp)

## Usage

Wrap the field. From `examples/app/app/orders/[id]/page.tsx`:

```tsx
<AssistedInput name="note" label="The order's note">
  <Textarea value={draft} onChange={(event) => setDraft(event.target.value)} />
</AssistedInput>
```

The Settings form in the screenshot gives its three inputs the name `setting` and an `id` each, in `examples/app/app/settings/page.tsx`.

## What the model sees

Same-name fields on a page are one tool that fills a field by `id`. Settings' `setting` is described as:

```txt wrap
Fill one of these by its id. name: Shop name; currency: Currency; email: Notification email.
```

It takes `{ id, value }`. The page's note shows what each field says now:

```md wrap
Its fields: setting (name: Shop name, now "Northwind"; currency: Currency, now "USD"; email: Notification email, now "alerts@northwind.example").
```

The fill in the screenshot answered without the note:

```txt wrap
Filled "Shop name"; it now says "Northwind Traders".
```

A fill changes the form, not the shop. Saving is the page's Save action, here a consequential one the user presses.

## States

### Filled by id in a dialog

![The New order dialog beside the sheet panel, filled with Acme, Chair, 2 and rush after four order_field calls.](https://superassist.app/_astro/input-dialog-light.C-LBtCuR.webp)

The New order dialog lends its customer select and its quantity and note inputs as `order_field`, beside a product picker lent through [AssistedField](https://superassist.app/components/package/assisted-field.md). A select's options become the values its field takes, so the customer's entry reads `customer: Customer, one of "" (Pick a customer), "Acme", "Globex", "Initech", "Umbrella"`. Four calls in one step filled the form, and Save creates the order.

## Props

| Prop            | Type           | Required | Description                                                                     |
| --------------- | -------------- | -------- | ------------------------------------------------------------------------------- |
| `name`          | `string`       | Yes      | The field's tool name. Same-name fields on one page are one tool.               |
| `label`         | `string`       | Yes      | What the field holds. Shown in the tool's description and the page's note.      |
| `id`            | `string`       | No       | The field's id within a same-name group.                                        |
| `consequential` | `boolean`      | No       | `true` rings the field for the user to fill.                                    |
| `trace`         | `boolean`      | No       | Shows the fill on the page with a ring. Defaults to the provider's `trace`.     |
| `children`      | `ReactElement` | Yes      | One element whose `ref` reaches the field's DOM element. Its own `ref` is kept. |

- Throws `Render an assisted field inside an AssistedPage` outside a page.
- Reads the element's kind when it mounts, and a select's options then.
- Fills by the element's kind:

| Element                   | Fill                                                  | Options       | Value in the note                 |
| ------------------------- | ----------------------------------------------------- | ------------- | --------------------------------- |
| `input`, `textarea`       | The element's own value setter, then an `input` event | None          | The value as a JSON string        |
| `input type="password"`   | As above                                              | None          | `(filled)` or `(empty)`           |
| Checkbox, `role="switch"` | A click when its state is not the asked `on` or `off` | `on`, `off`   | `on` or `off`                     |
| `select`                  | The element's own value setter, then a `change` event | Its `option`s | The value as a JSON string        |
| Anything else             | None. Rings it                                        | None          | Its trimmed text as a JSON string |

- Text values longer than 200 characters are cut and end with `…`.
- A fill checks the element first. Missing, disabled (`:disabled` or `aria-disabled="true"`) or read-only (`readonly` or `aria-readonly="true"`), it answers with an error and fills nothing.
- `consequential`, or an element of no known kind, rings the element and answers that filling is the user's. Its label gains ` (consequential)`.
- A fill waits for pending React updates to commit, then answers `Filled "<label>"; it now says <value>.`
- With `trace`, a fill flashes a ring on the element, gone after a second.
- Exact answers are in [Model context](https://superassist.app/reference/model-context.md#field-answers).

## useAssistedInput

```ts
useAssistedInput<T extends HTMLElement = HTMLElement>(options: AssistedInputOptions): RefObject<T | null>
```

The hook behind `AssistedInput`. `AssistedInputOptions` is `{ name, label, id?, consequential?, trace? }`, as in the table above. Attach the returned ref to the field. Throws outside an `AssistedPage`.

## See also

- [Lend a form's fields](https://superassist.app/how-to/lend-form-fields.md).
- [AssistedField](https://superassist.app/components/package/assisted-field.md) for a control that keeps its value in state.
- [How model context composes](https://superassist.app/explanation/model-context.md).

---

# AssistedField

> Lends a control that keeps its value in state, such as a custom picker, as a field the assistant fills through your setter.

`AssistedField` lends a control that keeps its value in state, not in a DOM field, as a field the assistant fills. It takes the value to show and the function that sets it.

![The New order dialog beside the sheet panel. The product picker's Desk button is selected, and the expanded order_field call answers Filled Product; it now says Desk.](https://superassist.app/_astro/field-light.DOo_8DQ0.webp)

## Usage

Pass the value and its setter, and wrap the control. From `examples/app/app/orders/new-order.tsx`:

```tsx
<AssistedField
  name="order_field"
  id="product"
  label="Product"
  options={products.map((value) => ({ value }))}
  value={draft.product}
  onFill={(value) => set("product", value)}
>
  <div role="group" aria-label="Product" className="flex gap-1">
    {products.map((name) => (
      <Button
        key={name}
        type="button"
        aria-pressed={draft.product === name}
        size="sm"
        variant={draft.product === name ? "secondary" : "ghost"}
        onClick={() => set("product", name)}
      >
        {name}
      </Button>
    ))}
  </div>
</AssistedField>
```

The child is only the ring's target. The value comes from `value`, and a fill goes through `onFill`.

## What the model sees

The picker shares the name `order_field` with the dialog's [AssistedInput](https://superassist.app/components/package/assisted-input.md) fields, so it is one entry of that tool. With `options`, its entry lists the values it takes:

```txt wrap
Fill one of these by its id. customer: Customer, one of "" (Pick a customer), "Acme", "Globex", "Initech", "Umbrella"; product: Product, one of "Chair", "Desk", "Lamp", "Monitor"; quantity: Quantity; note: Note.
```

The dialog's note shows what it says now, as for any field:

```md wrap
Its fields: order_field (customer: Customer, now ""; product: Product, now ""; quantity: Quantity, now "1"; note: Note, now "").
```

The fill in the screenshot called `onFill`, waited for React to commit, and answered with `value` as rendered:

```txt wrap
Filled "Product"; it now says "Desk".
```

## Props

| Prop            | Type                         | Required | Description                                                                                    |
| --------------- | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `name`          | `string`                     | Yes      | The field's tool name. Same-name fields on one page are one tool.                              |
| `label`         | `string`                     | Yes      | What the field holds. Shown in the tool's description and the page's note.                     |
| `id`            | `string`                     | No       | The field's id within a same-name group.                                                       |
| `consequential` | `boolean`                    | No       | `true` rings the child for the user to fill.                                                   |
| `trace`         | `boolean`                    | No       | Shows the fill on the page with a ring. Defaults to the provider's `trace`.                    |
| `options`       | `AssistedFieldOption[]`      | No       | The only values the field takes. `AssistedFieldOption` is `{ value: string; label?: string }`. |
| `value`         | `string`                     | Yes      | What the field says now. The note shows it as a JSON string.                                   |
| `onFill`        | `(value: string) => unknown` | Yes      | Sets the field to the value the assistant chose. Awaited.                                      |
| `children`      | `ReactElement`               | Yes      | One element whose `ref` reaches a DOM element, the ring's target.                              |

- Throws `Render an assisted field inside an AssistedPage` outside a page.
- A fill checks the child as `AssistedInput` does, calls `onFill`, waits for pending React updates to commit, then answers with `value` as rendered.
- The field is lent again only when `name`, `label`, `id`, `consequential`, `trace` or the content of `options` changes. `value` and `onFill` are read at call time.
- A tool's `value` parameter gains an enum only when every field of that name has `options`. New order's `order_field` mixes the picker with two text inputs, so it has none.

## See also

- [Lend a form's fields](https://superassist.app/how-to/lend-form-fields.md#lend-a-control-that-is-not-a-native-field).
- [Model context](https://superassist.app/reference/model-context.md#field-tools) gives the field tool's template.

---

# useAssistedTool

> Lends a tool that runs in the browser, scoped to its page under an AssistedPage and global elsewhere.

`useAssistedTool` lends a tool that runs in the browser: a page's tool under an `AssistedPage`, listed in its note and gone with it, or a global tool anywhere else.

![Orders beside the sheet panel, filtered to the three orders waiting to ship. The expanded filter_orders call answers Showing the orders that are to ship.](https://superassist.app/_astro/tool-light.D1lOcMrU.webp)

## Usage

Call it in a component under the page. From `examples/app/app/orders/page.tsx`:

```tsx
useAssistedTool("filter_orders", {
  description: "Show only the orders with one status, or all of them.",
  parameters: {
    type: "object",
    properties: { status: { type: "string", enum: filters } },
    required: ["status"],
  },
  execute: ({ status }: { status: Filter }) => {
    setFilter(status);
    return `Showing ${status === "all" ? "all orders" : `the orders that are ${status}`}.`;
  },
});
```

## What the model sees

The tool's `description` and its parameters' JSON Schema, here `status`, one of `all`, `to ship`, `shipped` and `cancelled`. As a page's tool it is named in the Orders note:

```md wrap
Its tools: filter_orders, get_page_content.
```

The call in the screenshot answered with what `execute` returned:

```txt wrap
Showing the orders that are to ship.
```

## States

### A global tool

![The sheet panel on Customers. The expanded get_shop_summary call answers with the shop's order and customer counts.](https://superassist.app/_astro/tool-global-light.DlQKNVhG.webp)

The example's shell lends `get_shop_summary` outside every `AssistedPage`, so it works from any page and no note names it. From `examples/app/app/shell.tsx`:

```tsx
useAssistedTool("get_shop_summary", {
  description: "How many orders and customers the shop has. Works from any page.",
  parameters: { type: "object", properties: {} },
  execute: () => ({ orders: shop.orders.length, customers: shop.customers.length }),
});
```

It answered on Customers with `{ "orders": 8, "customers": 4 }`.

## Signature

```ts
useAssistedTool<TArgs extends Record<string, unknown>, TResult>(
  name: string,
  tool: AssistedTool<TArgs, TResult>,
): void
```

| `AssistedTool` field | Type                                             | Required | Description                                                                                                     |
| -------------------- | ------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `description`        | `string`                                         | Yes      | What the tool does, for the model.                                                                              |
| `parameters`         | JSON Schema object or Standard Schema            | Yes      | The arguments. A Standard Schema such as zod types `execute`'s arguments.                                       |
| `execute`            | `(args, context) => TResult \| Promise<TResult>` | Yes      | Runs the call. `context` is the call's execution context: `toolCallId`, `abortSignal` and `human`.              |
| `toModelOutput`      | `({ toolCallId, input, output }) => parts`       | No       | What the model sees in place of the result: `text` parts and `file` parts with base64 `data` and a `mediaType`. |
| `render`             | `ToolCallMessagePartComponent`                   | No       | Tool UI for the call in the thread. Pass a stable component.                                                    |
| `consequential`      | `boolean`                                        | No       | `true` asks in the panel before `execute` runs.                                                                 |
| `question`           | `(args) => string`                               | No       | With `consequential`, the card's question for this call.                                                        |

- Under an `AssistedPage`, the tool belongs to the page and the note lists it. Elsewhere it is global and no note lists it.
- The tool is lent on mount and leaves on unmount. It is lent again when `description` or the parameters' JSON Schema changes.
- `execute` always runs the latest closure.
- A throw answers `{ error: "<name> failed: <message>" }`.
- Arguments the schema rejects answer `{ error: "<name> got arguments its parameters reject: <issues>" }`.
- With `toModelOutput`, the result still shows in the thread, and its images show under it, while the model gets the parts. Over 4 files, or a file over 5 MB, answers `{ error }` instead. A model that takes no files gets the text parts and a line counting the files it missed.
- With `consequential`, the description gains ` (asks first)`. The panel's card shows `question(args)`, or the description without one. A denial answers with the decline text and `execute` does not run.
- With `consequential` and no `render`, the [Confirm card](https://superassist.app/components/cards/confirm-card.md), or `cards.confirm` on the provider, renders the call inline, outside the tool group. A `render` of your own replaces it and must answer the pause with `resume({ approved: boolean })`.

`AssistedToolFailure` is `{ error: string }`.

## See also

- [Lend a tool](https://superassist.app/how-to/lend-a-tool.md).
- [How model context composes](https://superassist.app/explanation/model-context.md).

---

# AssistedDevtools

> The devtools with an Assisted pages tab that shows what the open page lends.

`AssistedDevtools` lends nothing. It mounts the devtools with an Assisted pages tab that shows what the open page lends, as the next turn will send it.

![The devtools window on Orders with the Assisted pages tab open: the page's name, the note the next turn sends, and get_page_content's answer.](https://superassist.app/_astro/devtools-light.F5RE1EYz.webp)

## Usage

Import it from the `devtools` entry and render it inside `AssistedProvider`. From `examples/app/app/assistant.tsx`:

```tsx
import { AssistedDevtools } from "@super-assist/react/devtools";
```

```tsx
<AssistedProvider
  runtime={runtime}
  destinations={destinations}
  navigate={(path) => router.push(withMode(path))}
>
  <Layout>{children}</Layout>
  <AssistedDevtools />
</AssistedProvider>
```

The launcher sits in the bottom-right corner in development. `DevToolsModal` renders nothing in production builds.

## What the model sees

Nothing from the devtools. The tab shows what the other components lend: the open page's note under Note the next turn sends, what `get_page_content` answers now, and every lent tool with its description. It re-reads every second.

## States

### Actions and fields

![The Assisted pages tab on Settings, scrolled to Actions and Fields: save_settings with a ring chip, the setting field tool with its ids and what each field says now, then the page and global tools.](https://superassist.app/_astro/devtools-fields-light.vujbOcx9.webp)

On Settings, `save_settings` carries a ring chip read from its marker, and the `setting` field tool lists its ids and what each field says now. The [devtools reference](https://superassist.app/reference/devtools.md#the-tab) lists every section of the tab.

## Props

None. To add the tab to a `DevToolsModal` of your own, pass `assistedPagesPlugin` from the same entry, as the [devtools reference](https://superassist.app/reference/devtools.md) describes.

## See also

- [Mount the devtools](https://superassist.app/how-to/mount-devtools.md).

---

# Roots and window

> AssistedPanel and its roots Floating, Sheet and Embedded, the Main column, the Launcher that opens a closed panel, the host-placed Trigger and the window controls.

`AssistedPanel` shows the assistant's conversation beside the page: a floating window, a sheet that takes its space from the page, or embedded where the host places it. Each mode is a root part. The roots hold the window, and every other part renders inside one, in a row of two columns: `Threads`, when the panel shows the thread list beside the conversation, and `Main`, which holds the rest.

![The floating panel over the Orders table, headed Assistant, On Orders. The user asked to ship Globex's order and the assistant says it is shipped.](https://superassist.app/_astro/panel-light.BFvJVRcu.webp)

## Usage

The one-liner picks a root by `mode` and renders its default composition. From `examples/app/app/assistant.tsx`, with the example's props:

```tsx
<AssistedPanel mode="floating" threads models={models} devtools={<AssistedDevtoolsPanel />} />
```

The roots take the same props as members of `AssistedPanel`. With children, a root renders exactly those, and `Main` is the column the header, the conversation and the composer go in:

```tsx
<AssistedPanel.Floating defaultPosition="bottom-left">
  <AssistedPanel.Main>
    <AssistedPanel.Header />
    <AssistedPanel.Conversation />
    <AssistedPanel.Composer />
  </AssistedPanel.Main>
</AssistedPanel.Floating>
```

## What the model sees

Nothing from the roots. They render the runtime's thread, and the header reads the open page's name from `useAssisted()`.

## Parts

| Part                           | Kind      | Renders                                                                                                   |
| ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------- |
| `AssistedPanel`                | One-liner | `Floating`, `Sheet` or `Embedded` by `mode`, with the root's default composition.                         |
| `AssistedPanel.Floating`       | Root      | A window portaled at z-index 50, dragged by its header and resized at its edges. Escape closes it.        |
| `AssistedPanel.Sheet`          | Root      | An `aside`, `w-md` wide, that takes its space from the page, with no overlay.                             |
| `AssistedPanel.Embedded`       | Root      | The conversation where the host places it. It is always shown and has no launcher.                        |
| `AssistedPanel.Main`           | Container | The column beside `Threads` that holds the header, the conversation, the composer and the footer.         |
| `AssistedPanel.Launcher`       | Leaf      | Opens a closed panel. Floating: a rounded button at the bottom corner. Sheet: a 48 px rail with a button. |
| `AssistedPanel.Trigger`        | Leaf      | A small "Assistant" button for the host's own toolbar. It opens and closes the panel.                     |
| `AssistedPanel.WindowControls` | Leaf      | Minimize, Maximize and Restore. Floating only, nothing in the other modes.                                |

### Default composition

| Part     | No children                                                                                                                                |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Any root | `Threads` when `threads="side"`, then `Main`. `Floating` and `Sheet` render the `Launcher` while closed.                                   |
| `Main`   | `Header` except in `Embedded`, `ThreadSelect` when `threads="select"`, `Conversation`, `Composer`, `ThreadDrawer` when `threads="drawer"`. |

`Floating` and `Sheet` render the `Launcher` beside their children unless `launcher` is `false`.

## States

### Floating, closed

![The Orders page with the panel closed: a rounded Assistant button in the bottom-right corner.](https://superassist.app/_astro/panel-closed-light.GEClx5Mt.webp)

### Floating, minimized

![The floating panel minimized to its header, with Restore and Close.](https://superassist.app/_astro/panel-minimized-light.C88th5C3.webp)

### Sheet

![The sheet panel beside the Orders table, taking its width from the page, with the same conversation.](https://superassist.app/_astro/panel-sheet-light.C-Bfhi_y.webp)

### Sheet, closed

![The Orders table with the sheet closed to a slim rail holding the assistant's button.](https://superassist.app/_astro/panel-sheet-closed-light.D0q81hoH.webp)

### Embedded

![The embedded panel in a column beside Settings, with no header: the user asked to change the shop name and the assistant filled it.](https://superassist.app/_astro/panel-embedded-light.g7AlZOO-.webp)

### Trigger

![The shop's navigation bar with the Assistant button beside Reset shop, in its quiet closed style.](https://superassist.app/_astro/trigger-light.H7HoDN0S.webp)

While the panel is open, the trigger is filled:

![The same navigation bar while the panel is open: the Assistant button is filled.](https://superassist.app/_astro/trigger-open-light.C_Z279jP.webp)

## Props

### Root props

`Floating`, `Sheet`, `Embedded` and the one-liner take these. `Embedded` takes every one but `launcher`.

| Prop           | Type                                                  | Description                                                                                                            |
| -------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `threads`      | `boolean \| "select" \| "menu" \| "drawer" \| "side"` | The thread picker's style, `true` meaning `"menu"`. Off by default. See [Threads](https://superassist.app/components/panel/threads.md).         |
| `models`       | `readonly ModelOption[]`                              | The models the composer's `ModelSelector` offers. The [data parts](https://superassist.app/components/panel/data-parts.md) need them.           |
| `defaultModel` | `string`                                              | The id of the model picked at first. The first of `models` without one.                                                |
| `title`        | `ReactNode`                                           | The header's name and the launcher's label. "Assistant" by default.                                                    |
| `icon`         | `ReactNode`                                           | Shown before the title and on the launcher. The assistant's logo by default.                                           |
| `description`  | `string`                                              | The header's line when no assisted page is open.                                                                       |
| `devtools`     | `ReactNode`                                           | What the header's Bug button opens, usually [`<AssistedDevtoolsPanel />`](https://superassist.app/reference/devtools.md). No button without it. |
| `launcher`     | `boolean`                                             | `false` leaves the launcher out, for a panel opened only by a `Trigger` or `useAssisted().open`.                       |
| `className`    | `string`                                              | Classes for the root's outer element.                                                                                  |
| `children`     | `ReactNode`                                           | The parts to render in place of the default composition.                                                               |

The one-liner adds `mode`, `"floating" | "sheet" | "embedded"`, required.

### Window props

`Floating` and the one-liner in floating mode take these too.

| Prop              | Type                                                           | Description                                                                                                |
| ----------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `defaultPosition` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | The corner it first opens in, 24 px in, and the launcher's side. `"bottom-right"` by default.              |
| `defaultSize`     | `{ width: number; height: number }`                            | Its first size, cut to the viewport less 24 px. 420 by 640 px by default. At least 320 by 360 px.          |
| `resizable`       | `boolean`                                                      | Resized at its edges and corners. On by default.                                                           |
| `draggable`       | `boolean`                                                      | Dragged by its header. On by default.                                                                      |
| `windowControls`  | `boolean`                                                      | The Minimize, Maximize and Restore buttons, and maximizing on a double-click of the header. On by default. |

The position and size persist across opens.

### Leaf props

`Launcher` and `Trigger` take a button's props and `asChild`. With `asChild`, the part renders your element in place of its button and keeps its behavior:

```tsx
<AssistedPanel.Trigger asChild>
  <Button>Help</Button>
</AssistedPanel.Trigger>
```

`Launcher` renders nothing while the panel is open. `Trigger` sets `aria-pressed` while it is open. `WindowControls` takes `className`.

Types: `AssistedPanelProps`, `AssistedPanelFloatingProps`, `AssistedPanelSheetProps`, `AssistedPanelEmbeddedProps`, `AssistedPanelOptions` (the root props) and `AssistedPanelWindowProps`.

- Render the roots inside `AssistedProvider`. Floating and sheet read and set `useAssisted()`'s `isOpen`.
- Every root carries `data-super-assist`, which scopes the [styles](https://superassist.app/reference/styles.md).

## See also

- [Place the panel](https://superassist.app/how-to/place-the-panel.md) picks a mode and opens it from your chrome.
- [Rearrange the panel's parts](https://superassist.app/how-to/rearrange-the-panel.md) composes the roots by hand.
- [Parts and the default composition](https://superassist.app/explanation/parts-and-the-default-composition.md) explains the model.

---

# Header

> The Header and Footer rows and the parts that sit in them, Icon, Title, PageLine, Close and Devtools.

The header is the panel's top row: who the assistant is, which page it is on, and the buttons that act on the panel. The footer is an optional row at the bottom.

![The floating panel minimized to its header: the logo, Assistant, On Orders, the threads and search buttons, Restore and Close.](https://superassist.app/_astro/panel-minimized-light.C88th5C3.webp)

## Usage

`Header` with no children renders its default. With children, it renders those. This header names the assistant and keeps only the devtools and Close:

```tsx
<AssistedPanel.Sheet>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.Icon>
        <ShopLogo />
      </AssistedPanel.Icon>
      <AssistedPanel.Title>Shop assistant</AssistedPanel.Title>
      <AssistedPanel.Devtools>
        <AssistedDevtoolsPanel />
      </AssistedPanel.Devtools>
      <AssistedPanel.Close />
    </AssistedPanel.Header>
    <AssistedPanel.Conversation />
    <AssistedPanel.Composer />
  </AssistedPanel.Main>
</AssistedPanel.Sheet>
```

## What the model sees

Nothing. `PageLine` reads the open page's name, and no part lends anything.

## Parts

| Part                     | Kind      | Renders                                                                                                             |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `AssistedPanel.Header`   | Container | A 40 px row. In a floating panel it is the drag handle, and a double-click maximizes.                               |
| `AssistedPanel.Footer`   | Container | A row with a top border. Nothing without children.                                                                  |
| `AssistedPanel.Icon`     | Container | Its children, else the root's `icon`, else the assistant's logo.                                                    |
| `AssistedPanel.Title`    | Container | Its children, else the root's `title`, else "Assistant".                                                            |
| `AssistedPanel.PageLine` | Container | Its children, else "On" and the open page's name, else the root's `description`. Nothing when all are empty.        |
| `AssistedPanel.Close`    | Leaf      | Closes the panel.                                                                                                   |
| `AssistedPanel.Devtools` | Leaf      | A Bug button that opens its children, else the root's `devtools`, in a window of their own. Nothing without either. |

### Default composition

`Header` with no children renders, in order:

1. `Icon`, or `ThreadDrawerToggle` when `threads="drawer"`.
2. `Title` and `PageLine`, or `ThreadTitle` and `PageLine` when `threads="drawer"`.
3. `ThreadMenu` when `threads` is `true` or `"menu"`.
4. `NewThread` when `threads` is `true`, `"menu"` or `"drawer"`.
5. `ConversationSearchToggle`.
6. `Devtools`.
7. `WindowControls` in a floating panel with `windowControls` on.
8. `Close`, except in an embedded panel.

`Footer` has no default. The embedded root's `Main` has no header, and `threads="side"` places no thread part in the header.

## Props

| Part                                            | Props                                         |
| ----------------------------------------------- | --------------------------------------------- |
| `Header`, `Footer`, `Icon`, `Title`, `PageLine` | `className`, `children`                       |
| `Devtools`                                      | `className`, `children`: the devtools to open |
| `Close`                                         | A button's props and `asChild`                |

With `asChild`, `Close` renders your element in place of its icon button and keeps its behavior. `Devtools` has no `asChild`: its children are the devtools.

The devtools window is 760 by 520 px in the top-left corner, dragged and resized like the panel. The Bug button or the window's Close shuts it.

## See also

- [Threads](https://superassist.app/components/panel/threads.md) for the thread parts the default header places.
- [Mount the devtools](https://superassist.app/how-to/mount-devtools.md).

---

# Threads

> The thread parts, Threads, ThreadMenu, ThreadSelect, ThreadDrawerToggle, ThreadDrawer, ThreadTitle, NewThread and DeleteThread, and the four picker styles.

The thread parts pick, start and delete threads. They show the end user's threads, which Super Assist keeps, most recently active first. New thread, rename and delete go to Super Assist.

![The floating panel with the Threads menu open below the header: Shop typed in its search box, and the one matching thread, Shop questions.](https://superassist.app/_astro/threads-menu-light.BgIRdyg4.webp)

## Usage

Set `threads` on the root and the default header places the parts for that style:

```tsx
<AssistedPanel mode="floating" threads="drawer" />
```

Or place them yourself. This header opens a drawer and starts a thread, with the host's own buttons:

```tsx
<AssistedPanel.Floating launcher={false}>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.ThreadDrawerToggle asChild>
        <IconButton icon={PanelLeft} />
      </AssistedPanel.ThreadDrawerToggle>
      <AssistedPanel.ThreadTitle />
      <AssistedPanel.NewThread asChild>
        <IconButton icon={Plus} />
      </AssistedPanel.NewThread>
      <AssistedPanel.Close />
    </AssistedPanel.Header>
    <AssistedPanel.ThreadDrawer />
    <AssistedPanel.Conversation />
    <AssistedPanel.Composer />
  </AssistedPanel.Main>
</AssistedPanel.Floating>
```

`ThreadDrawer` overlays the conversation, so it sits in `Main` beside the other parts, not in the header.

For a panel wide enough to show the list all the time, `Threads` is a column before `Main`. The one-liner places it with `threads="side"`, and leaves the thread parts out of the header:

```tsx
<AssistedPanel.Embedded threads="side" />
```

Or place `ThreadList` in your layout, here beside an embedded panel. From `examples/app/app/assistant.tsx`:

```tsx
import { AssistedPanel, ThreadList } from "@super-assist/react";

<div className="flex h-dvh">
  <aside className="w-64 shrink-0 border-e p-2">
    <ThreadList />
  </aside>
  <main className="min-w-0 flex-1 overflow-y-auto p-6">{children}</main>
  <div className="w-md shrink-0 border-s">
    <AssistedPanel mode="embedded" />
  </div>
</div>;
```

## What the model sees

Nothing. Each part switches threads through the runtime.

## Parts

| Part                               | Kind | Renders                                                                                               |
| ---------------------------------- | ---- | ----------------------------------------------------------------------------------------------------- |
| `AssistedPanel.Threads`            | Row  | The thread list in a 256 px column before `Main`, with its New Thread button and search.              |
| `AssistedPanel.ThreadMenu`         | Leaf | A History button that opens a popover with a search over the threads and their previews.              |
| `AssistedPanel.ThreadSelect`       | Row  | A row with a native select over the threads, `NewThread` and `DeleteThread`.                          |
| `AssistedPanel.ThreadDrawerToggle` | Leaf | Opens and closes the drawer.                                                                          |
| `AssistedPanel.ThreadDrawer`       | Row  | The thread list in a 256 px column over the conversation. Picking a thread or the backdrop closes it. |
| `AssistedPanel.ThreadTitle`        | Text | The open thread's title, or "New thread".                                                             |
| `AssistedPanel.NewThread`          | Leaf | Starts a new thread.                                                                                  |
| `AssistedPanel.DeleteThread`       | Leaf | Deletes the open thread after a dialog asks. Disabled for a thread the runtime has not listed yet.    |

### Picker styles

| `threads`          | The default composition places                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `true` or `"menu"` | `ThreadMenu` and `NewThread` in the header.                                                             |
| `"select"`         | `ThreadSelect` in a row under the header.                                                               |
| `"drawer"`         | `ThreadDrawerToggle` and `ThreadTitle` in place of the icon and title, `NewThread`, and `ThreadDrawer`. |
| `"side"`           | `Threads` before `Main`, and nothing in the header.                                                     |

The menu's search reads each thread's title, and its `custom.group` and `custom.preview` when the runtime gives them. Threads without a title read "New thread" in the menu and "Untitled" in the select.

## Props

| Part                                                            | Props                          |
| --------------------------------------------------------------- | ------------------------------ |
| `ThreadMenu`, `ThreadDrawerToggle`, `NewThread`, `DeleteThread` | A button's props and `asChild` |
| `Threads`, `ThreadSelect`, `ThreadDrawer`, `ThreadTitle`        | `className`                    |

`ThreadList`, the list `Threads` and the drawer show, is exported on its own for a list in your layout.

## See also

- [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md#name-the-signed-in-user), so a user's threads follow them across browsers.
- [Header](https://superassist.app/components/panel/header.md) for where the default places them.

---

# Conversation

> The Conversation and the parts inside it, EmptyState, Messages, FollowUps, ScrollToBottom, HistorySkeleton, ConversationSearch and its toggle.

The conversation is the current thread's messages as the panel shows them, from the empty state to the last reply. It scrolls, and it holds the cards the assistant answers with.

![The sheet panel beside the Orders table: the user asked to ship Globex's order and the assistant says it is shipped.](https://superassist.app/_astro/panel-sheet-light.C-Bfhi_y.webp)

## Usage

`Conversation` with no children renders its default. With children, it renders those. This one keeps the search and swaps the assistant's message:

```tsx
function Mine() {
  return (
    <MessagePrimitive.Root className="rounded-lg border-s-2 border-teal-600 bg-teal-50 px-3 py-2 text-sm">
      <MessagePrimitive.Parts />
    </MessagePrimitive.Root>
  );
}

<AssistedPanel.Conversation>
  <AssistedPanel.ConversationSearch />
  <AssistedPanel.Messages components={{ AssistantMessage: Mine }} />
  <AssistedPanel.ScrollToBottom />
</AssistedPanel.Conversation>;
```

The parts stop where a single message begins. Inside a message, `Messages` takes `components` slots.

## What the model sees

Nothing from the parts. A starter the user picks is sent as the user's message, as typed.

## Parts

| Part                                     | Kind      | Renders                                                                                                  |
| ---------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `AssistedPanel.Conversation`             | Container | The scrolling viewport, centered up to 44 rem. Hidden while the settings panel is shown.                 |
| `AssistedPanel.HistorySkeleton`          | Leaf      | Placeholder lines while the runtime loads a thread's history.                                            |
| `AssistedPanel.EmptyState`               | Leaf      | In an empty thread: `What should we do on {page}?`, or `How can I help?` off any page, and the starters. |
| `AssistedPanel.Messages`                 | Leaf      | The thread's messages, with cards inline, day separators and the stopped-run card.                       |
| `AssistedPanel.FollowUps`                | Leaf      | The runtime's suggested follow-ups after the last reply.                                                 |
| `AssistedPanel.HandoffOffer`             | Leaf      | A **Talk to a person** button when the hosted runtime says a person looks needed. It sends the request.  |
| `AssistedPanel.Resolution`               | Leaf      | **Did this resolve your issue?** with Yes and No under a complete reply, when the hosted runtime asks.   |
| `AssistedPanel.ScrollToBottom`           | Leaf      | A round button pinned to the bottom while the view is scrolled up.                                       |
| `AssistedPanel.ConversationSearch`       | Leaf      | A search box over the thread's text with the hit count and previous and next. It scrolls to each hit.    |
| `AssistedPanel.ConversationSearchToggle` | Leaf      | A search button that shows and hides the default composition's search.                                   |

### Default composition

`Conversation` with no children renders `ConversationSearch` while the toggle is on, then `HistorySkeleton`, `EmptyState`, `Messages`, `FollowUps`, `HandoffOffer`, `Resolution` and `ScrollToBottom`.

### Hosted outcomes

`Resolution` and `HandoffOffer` show nothing unless the [hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md) asks for them. After each reply, Super Assist judges the exchange and tells the panel whether to ask about resolution and whether to offer a person; a thread handed to a person shows neither. An answer to the question is kept on the thread and shows as **Marked as resolved** or **Marked as unresolved**. See [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md#after-the-reply-a-decision-model-reads-the-exchange).

### Starters

`EmptyState` shows the open page's `starters`, else the provider's, as buttons that send. The runtime's own suggestions follow them. See [Make a page assisted](https://superassist.app/how-to/make-a-page-assisted.md#suggest-first-messages).

### Inside `Messages`

- **Day separator:** a date line above a message from another day than the one before.
- **Stopped run:** a reply the user stopped shows a card with Continue, which runs it again, and Discard, which deletes it.
- **Cards:** each tool call with a card renders inline. See [Cards](https://superassist.app/components.md#cards).

## Props

| Part                                                               | Props                                         |
| ------------------------------------------------------------------ | --------------------------------------------- |
| `Conversation`                                                     | `className`, `children`                       |
| `Messages`                                                         | `className`, `components`: `ThreadComponents` |
| `HistorySkeleton`, `EmptyState`, `FollowUps`, `ConversationSearch` | `className`                                   |
| `HandoffOffer`, `Resolution`                                       | `className`                                   |
| `ScrollToBottom`, `ConversationSearchToggle`                       | A button's props and `asChild`                |

`ThreadComponents` slots, each optional:

| Slot               | Type                                          | Replaces                                 |
| ------------------ | --------------------------------------------- | ---------------------------------------- |
| `AssistantMessage` | `ComponentType`                               | An assistant message.                    |
| `UserMessage`      | `ComponentType`                               | A user message.                          |
| `DaySeparator`     | `ComponentType<{ day: Date }>`                | The date line.                           |
| `ToolFallback`     | `ToolCallMessagePartComponent`                | A tool call without a card.              |
| `ToolGroup`        | `ComponentType<PropsWithChildren<{ group }>>` | The group around consecutive tool calls. |
| `ReasoningGroup`   | `ComponentType<PropsWithChildren<{ group }>>` | The group around reasoning.              |
| `TaskGroup`        | `ComponentType<{ group }>`                    | A task group.                            |

Build a message slot from `MessagePrimitive`, exported by the package. See [Make your own part](https://superassist.app/how-to/make-your-own-part.md).

## See also

- [Composer](https://superassist.app/components/panel/composer.md), the conversation's partner below it.
- [Parts and the default composition](https://superassist.app/explanation/parts-and-the-default-composition.md) for where parts stop and slots begin.

---

# Composer

> The Composer and the parts inside it, Input with its slash commands, Attachments, AddAttachment, Dictate, ModelSelector and Send.

The composer is where the user writes. Its input lists the open page's actions and fields when the user types `/`.

![The composer with a slash typed: a list of the Orders page's actions, each with what pressing it does.](https://superassist.app/_astro/composer-slash-light.C0qUjed6.webp)

## Usage

`Composer` with no children renders its default. With children, it renders those. This one keeps the input, the model picker and the send button:

```tsx
<AssistedPanel.Composer>
  <AssistedPanel.Input />
  <AssistedPanel.ModelSelector />
  <AssistedPanel.Send />
</AssistedPanel.Composer>
```

## What the model sees

What the user sends. `ModelSelector` also sets the model and the reasoning effort every message carries, as `config.modelName` and `config.reasoningEffort`. Super Assist answers an end user on the agent's own model and thinking level, so the choice doesn't change the reply. See [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md#the-agent-answers).

## Parts

| Part                          | Kind      | Renders                                                                                             |
| ----------------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `AssistedPanel.Composer`      | Container | The composer's box below the conversation, centered up to 44 rem. Files dropped on it attach.       |
| `AssistedPanel.Attachments`   | Leaf      | The files attached to the message, on a row of their own.                                           |
| `AssistedPanel.Input`         | Leaf      | The text box. Enter sends. `/` opens the page's slash commands.                                     |
| `AssistedPanel.AddAttachment` | Leaf      | A paperclip button that picks files.                                                                |
| `AssistedPanel.Dictate`       | Leaf      | A microphone button, then a stop button while dictating. Nothing when the runtime has no dictation. |
| `AssistedPanel.ModelSelector` | Leaf      | A model picker, with an effort control for models that have `efforts`. Nothing without models.      |
| `AssistedPanel.Send`          | Leaf      | Sends the message. While a reply runs, a stop button in its place.                                  |

### Default composition

`Composer` with no children renders `Attachments` and `Input` on rows of their own, then a row of controls: `AddAttachment`, `Dictate` and [`ContextDisplay`](https://superassist.app/components/panel/data-parts.md) on the left, `ModelSelector` and `Send` on the right.

### Slash commands

Typing `/` in `Input` lists the open page's actions, then its fields. Rows of one action list each row's label.

| Picked    | Inserts          | Hint                                                                                          |
| --------- | ---------------- | --------------------------------------------------------------------------------------------- |
| An action | Its label        | "Rings it for you to press" when `consequential`, "Asks you before it runs" when `"confirm"`. |
| A field   | `Set <label> to` | "Rings it for you to fill" when `consequential`.                                              |

With nothing lent, the list reads "This page lends no actions or fields". The placeholder reads "Ask, or type / for actions" while the page lends any, else "Send a message…".

## Props

| Part                               | Props                                                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Composer`                         | `className`, `children`                                                                                        |
| `Input`                            | `className`, `autoFocus` (on by default), `placeholder`                                                        |
| `Attachments`                      | `className`                                                                                                    |
| `AddAttachment`, `Dictate`, `Send` | A button's props and `asChild`                                                                                 |
| `ModelSelector`                    | `models`, else the root's `models`. `searchable`, `align`, `variant`, `size`, `className`, `contentClassName`. |

With `asChild`, `Send` replaces only the send button and `Dictate` only the start button. The stop and cancel buttons stay the package's.

## See also

- [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md), for what reaches the agent.
- [Add actions](https://superassist.app/how-to/add-actions.md) and [Lend a form's fields](https://superassist.app/how-to/lend-form-fields.md) for what the slash commands list.

---

# Data parts

> The parts that show and set what the model runs with, SettingsToggle, SettingsPanel, ContextDisplay, ContextBreakdown and QuotaBanner.

The data parts show what the model runs with and let the user change it. Only `ContextDisplay` is in a default composition, in the composer's controls; place the rest where you want them. Each renders nothing until it has data, so a part with nothing to show takes no space.

## Usage

Give the root `models`, then place the parts. This embedded panel puts a context ring and a settings button in its header, a breakdown and a quota banner in the settings panel, and a context bar in its footer:

```tsx
<AssistedPanel.Embedded models={models}>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.Title />
      <AssistedPanel.ContextDisplay />
      <AssistedPanel.SettingsToggle />
    </AssistedPanel.Header>
    <AssistedPanel.SettingsPanel>
      <AssistedPanel.ContextBreakdown />
      <AssistedPanel.QuotaBanner
        used={42}
        limit={50}
        unit="messages"
        resetsIn="3h"
        upgradeLabel="Upgrade"
      />
    </AssistedPanel.SettingsPanel>
    <AssistedPanel.Conversation />
    <AssistedPanel.Composer />
    <AssistedPanel.Footer>
      <AssistedPanel.ContextDisplay variant="bar" className="flex-1" />
    </AssistedPanel.Footer>
  </AssistedPanel.Main>
</AssistedPanel.Embedded>
```

## What the model sees

`SettingsPanel` adds to every message: its temperature as `callSettings.temperature`, and its system prompt box appended to `system`. Super Assist applies both to the turn. The model choice comes from the composer's `ModelSelector`, as `config.modelName`, and Super Assist answers on the agent's own model instead. The display parts send nothing.

## Parts

| Part                             | Kind      | Renders                                                                                                        |
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `AssistedPanel.SettingsToggle`   | Leaf      | A settings button that swaps the conversation for the settings panel. Nothing without the root's `models`.     |
| `AssistedPanel.SettingsPanel`    | Container | The model, a system prompt box and a temperature slider, then its children. Shown only while the toggle is on. |
| `AssistedPanel.ContextDisplay`   | Leaf      | How much of the model's context window the thread uses, as a ring, a bar or text.                              |
| `AssistedPanel.ContextBreakdown` | Leaf      | The window split into segments, Prompt and Reply by default.                                                   |
| `AssistedPanel.QuotaBanner`      | Leaf      | A banner with the user's quota, as you pass it.                                                                |

### Where the data comes from

| Part               | Reads                                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SettingsPanel`    | The root's `models` and the model the composer picked. Its own state for the prompt and the temperature.                                         |
| `ContextDisplay`   | The thread's token usage from the last reply's `metadata.usage`, and the window from `modelContextWindow` or the picked model's `contextWindow`. |
| `ContextBreakdown` | The same usage, or your `segments`, and the window from `limit` or the picked model's `contextWindow`.                                           |
| `QuotaBanner`      | Its props only.                                                                                                                                  |

`ContextDisplay` and `ContextBreakdown` read usage from a reply's `metadata.usage`. Super Assist's replies carry none, so `ContextDisplay` renders nothing and `ContextBreakdown` shows only the `segments` you pass.

## Props

### SettingsToggle

A button's props and `asChild`. It sets `aria-pressed` while the settings show.

### SettingsPanel

| Prop        | Type                       | Description                                              |
| ----------- | -------------------------- | -------------------------------------------------------- |
| `toggles`   | `readonly SettingToggle[]` | Switches under the slider: `{ key, label, detail, on }`. |
| `onToggle`  | `(key: string) => void`    | Called with a switch's `key` when the user flips it.     |
| `className` | `string`                   | Classes for its column.                                  |
| `children`  | `ReactNode`                | Rendered below the settings.                             |

### ContextDisplay

| Prop                 | Type                                     | Description                                                                                                     |
| -------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `variant`            | `"ring" \| "bar" \| "text"`              | `"ring"` by default.                                                                                            |
| `modelContextWindow` | `number`                                 | The window in tokens, over the model's own.                                                                     |
| `usage`              | `TokenUsage`                             | Token usage to show, over the thread's own.                                                                     |
| `segments`           | `readonly { label, tokens }[]`           | What the window holds by part: System, Tools, Messages. The popover then shows the breakdown, colored in order. |
| `side`               | `"top" \| "bottom" \| "left" \| "right"` | Where its popover opens.                                                                                        |
| `className`          | `string`                                 |                                                                                                                 |

### ContextBreakdown

| Prop        | Type                        | Description                                                                                   |
| ----------- | --------------------------- | --------------------------------------------------------------------------------------------- |
| `segments`  | `readonly ContextSegment[]` | `{ label, tokens, tint }`, `tint` a class for the segment's color. Replaces Prompt and Reply. |
| `limit`     | `number`                    | The window in tokens, over the model's own.                                                   |
| `className` | `string`                    |                                                                                               |

### QuotaBanner

| Prop           | Type         | Required | Description                          |
| -------------- | ------------ | -------- | ------------------------------------ |
| `used`         | `number`     | Yes      | What the user has used.              |
| `limit`        | `number`     | Yes      | Their limit.                         |
| `unit`         | `string`     | Yes      | What is counted, such as "messages". |
| `resetsIn`     | `string`     | Yes      | When it resets, such as "3h".        |
| `upgradeLabel` | `string`     | Yes      | The upgrade button's label.          |
| `onUpgrade`    | `() => void` | No       | Called when the user presses it.     |

It also takes a `div`'s props.

## See also

- [How a turn is answered](https://superassist.app/explanation/how-a-turn-is-answered.md#the-page-adds-what-it-lends), for which settings reach the agent.
- [Composer](https://superassist.app/components/panel/composer.md) for `ModelSelector`.

---

# Use the hosted runtime

> Choose the agent that answers, name the signed-in user, point the runtime at another Super Assist origin or at a route of your own, keep the open thread in the URL, and handle a refused connection.

`useAssistedRuntime` connects the panel to a Super Assist project with its publishable key. The [tutorial](https://superassist.app/tutorials/add-an-assistant.md) sets up a project and mounts the panel. This page covers the hook's other options. The [reference](https://superassist.app/reference/react.md#useassistedruntime) lists them all.

```tsx
const runtime = useAssistedRuntime({ key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY! });
```

## Answer with another agent

The project's default agent answers unless you pass `agent`, the id of another agent of your organization. The id is on the agent's page in the dashboard, behind the copy button beside its name:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  agent: process.env.NEXT_PUBLIC_SUPER_ASSIST_AGENT,
});
```

Each agent keeps its own threads for each end user, so another agent starts with another thread list.

## Name the signed-in user

Pass the signed-in user, and their threads follow them across browsers. Super Assist takes the id as you give it and records it as unverified, so use an id that is stable and not guessable by other users:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  user: session ? { id: session.user.id, name: session.user.name } : undefined,
});
```

Without a user, the browser is a visitor. The hook keeps a random id in `localStorage`, one per publishable key, and the visitor's threads stay with that browser until its storage is cleared. A visitor's threads are never merged into a user's when they sign in.

## Point at another Super Assist origin

`host` is the Super Assist origin, `https://superassist.app` by default. Set it when your app talks to another one, such as Super Assist's own development server on `http://localhost:4310`. An unset variable falls back to the default:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  host: process.env.NEXT_PUBLIC_SUPER_ASSIST_HOST,
});
```

## Point at a route of your own

Super Assist's dashboard chats with an agent over a route its session cookie authenticates, with no publishable key. `basePath` points the runtime at such a route on the page's own origin: the thread list opens on `basePath`, and each thread on `basePath/:id`, both the Cloudflare Agents sockets the hosted route serves. Pass a key or a `basePath`, not both:

```tsx
const runtime = useAssistedRuntime({ basePath: `api/v1/agents/${agent.id}/threads` });
```

## Keep the open thread in the URL

The hook picks a thread on its own: the one you pass as `thread`, else the most recent, and a new one when there are none. `onThreadChange` reports every pick, so a page can keep the open thread in its URL and open the same thread after a reload:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  thread: searchParams.get("thread") ?? undefined,
  onThreadChange: (id) => router.replace(`?thread=${id}`),
});
```

## Handle a refused connection

Super Assist checks the key, the page's origin, the agent and the end user before it opens anything. A refused connection closes with a code, and the hook does not retry it:

| Code   | Why                                                                              | Fix                                                             |
| ------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `4401` | The publishable key is unknown, or it was rolled.                                | Use the project's current key.                                  |
| `4403` | The page's origin is not one of the project's allowed origins.                   | Add the origin under **Allowed origins** on the project's page. |
| `4404` | The project has no default agent, or `agent` names no agent of the organization. | Pick the project's **Default agent**, or pass an agent's id.    |
| `4400` | Neither a user nor a visitor id was sent.                                        | Pass a `user` with an `id`, or leave `user` out for a visitor.  |

A new project allows `http://localhost:3000` and `http://localhost:5173`, so add your production origin before you deploy. Open the project in the dashboard, enter the origin under **Allowed origins**, and press **Add**. The [API](https://superassist.app/docs/api) sets `allowedOrigins` and `defaultAgentId` too, with `PATCH /api/v1/projects/{id}`.

An allowed origin is a scheme, host and optional port, such as `https://shop.example.com`, or `https://*.example.com` for every subdomain.

`onConnectionError` gets the error with the code in `error.code` and the reason in `error.reason`. It logs to the console by default. To show it, keep it in state:

```tsx
const [refused, setRefused] = useState<string>();
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  onConnectionError: (error) => setRefused(error.reason),
});
```

---

# Connect a coding agent

> Install the Super Assist plugin in Claude Code or the skill in another agent, add the MCP server by URL, run setup and sync, and disconnect an agent under Account.

The Super Assist plugin gives a coding agent what it needs to work on your app: a skill that teaches it `@super-assist/react` and runs commands such as `setup` and `sync`, and a connection to Super Assist's MCP server, through which it creates your agent, project, pages and journeys as you, with no key to copy. Claude Code installs the whole plugin; other agents install the skill and add the MCP server by its URL.

## Install the plugin in Claude Code

In Claude Code, from your app's repository:

1. Add the marketplace and install the plugin:

   ```txt
   /plugin marketplace add mertdogar/super-assist-templates
   /plugin install super-assist@super-assist
   ```

   The install asks for a scope: user for all your repositories, project to share it with everyone who works in this one through `.claude/settings.json`, or local for you in this one. When the install summary says to, run `/reload-plugins`.

2. Run `/mcp`, select `plugin:super-assist:api`, and [sign in](#sign-in-to-super-assist) in the browser.

From a shell, the same steps are `claude plugin marketplace add mertdogar/super-assist-templates` and `claude plugin install super-assist@super-assist`.

The plugin brings three things:

- The `super-assist` skill and its [commands](#run-the-skills-commands).
- The MCP server `plugin:super-assist:api`, at `https://superassist.app/mcp`.
- Two hooks. At the start of a session they note the app's assisted pages, and when Claude finishes a turn that changed them, they ask it to [sync](#keep-the-page-catalog-in-sync).

Claude Code doesn't update plugins from this marketplace on its own. Turn updates on under `/plugin` › **Marketplaces** › **Enable auto-update**, or update by hand with `/plugin marketplace update super-assist`.

## Install the skill in another agent

Codex, Cursor, GitHub Copilot and the other agents the `skills` CLI supports install the skill from your app's repository:

```bash
npx skills add mertdogar/super-assist-templates
```

The skill comes with its commands and the script that scans your app's routes, which needs Node and nothing else. Installed this way it has no hooks, so ask for `sync` after you change pages, and no MCP server until you [add it](#add-the-mcp-server-by-url). In Claude Code, install the plugin instead: with both, Claude Code has the skill twice.

## Add the MCP server by URL

The MCP server is at `https://superassist.app/mcp`. A client signs in to it in the browser, so no key goes in its configuration.

### Codex

Add the server and sign in:

```sh
codex mcp add super-assist --url https://superassist.app/mcp
codex mcp login super-assist
```

The server can also go in `~/.codex/config.toml` by hand, followed by the same `codex mcp login`:

```toml title="~/.codex/config.toml"
[mcp_servers.super-assist]
url = "https://superassist.app/mcp"
```

The Codex IDE extension and the ChatGPT desktop app share this configuration.

### Cursor

Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` in the app's repository:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "super-assist": {
      "url": "https://superassist.app/mcp"
    }
  }
}
```

Cursor signs in with OAuth to servers that require it, as this one does. Turn the server on or off from **Customize** in the sidebar.

### VS Code

Run **MCP: Add Server** from the Command Palette, choose **HTTP (HTTP or Server-Sent Events)**, enter `https://superassist.app/mcp` and a server ID such as `super-assist`, and pick where to save it. The same server in a workspace's `.vscode/mcp.json`:

```json title=".vscode/mcp.json"
{
  "servers": {
    "super-assist": {
      "type": "http",
      "url": "https://superassist.app/mcp"
    }
  }
}
```

A browser window opens to sign in the first time VS Code connects to the server.

### Other clients

Claude and ChatGPT connect at the same URL. A client Super Assist doesn't accept yet, such as Windsurf or Gemini CLI, calls the API with an organization key and curl instead, as [Set up through the API](https://superassist.app/how-to/set-up-through-the-api.md) shows.

## Sign in to Super Assist

Signing in from a coding agent opens superassist.app in the browser. Sign up there first if you're new: signing up in the middle of connecting doesn't return you to the agent.

1. Sign in to Super Assist.
2. When you belong to several organizations, pick the one the agent works in.
3. Press **Allow** under "_Claude Code_ wants to act as you in _your organization_". You allow each client once per organization.

The connection acts as you in that organization. It can do what you can do in the dashboard, with your role read on every call, until you [disconnect it](#disconnect-a-coding-agent) or leave it unused for 30 days. To work in another organization, sign in again: in Claude Code, `/mcp` › `plugin:super-assist:api` › **Clear authentication**, then sign in.

## Run the skill's commands

In Claude Code, type `/super-assist` and a command, such as `/super-assist setup`. In another agent, ask for the command by name, such as "run super-assist sync".

| Command          | What it does                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `setup`          | Adds the panel to the app, reuses or creates its agent and project, writes the publishable key, syncs, proposes journeys |
| `sync [dir]`     | Makes the page catalog match the code, corrects `destinations`, and asks about journeys that name what's gone            |
| `page [route]`   | Makes a route's page assisted: its name, instructions, content, actions and fields                                       |
| `journey [goal]` | Drafts journeys from the page catalog, as `manual` drafts a member publishes                                             |
| `doctor`         | Checks the library, the key, the connection, the project, catalog drift and journeys naming what's gone                  |

`/super-assist` alone checks the app and recommends the next command, then waits for you to pick one. For any other work with the library, the skill tells the agent which piece to lend for what and which page of these docs to read.

The skill finds the app's project by the publishable key in the app's env file, so it writes nothing else to the repository. When the MCP server isn't connected, it asks you to connect it, or to use an organization key with curl if you'd rather.

The MCP server has two tools. `search` looks up a route in the API's description. `execute` runs the agent's code against the API as you, and Claude Code shows the code before each run. To stop Claude Code asking before `search`, allow it in your settings:

```json title=".claude/settings.json"
{
  "permissions": {
    "allow": ["mcp__plugin_super-assist_api__search"]
  }
}
```

## Keep the page catalog in sync

Sync makes the project's page catalog match the code. It scans the app's routes and the assisted pages they render, fills in what the scan can't read, such as a page name built from a variable, corrects `destinations`, and posts every page with [`replace: true`](https://superassist.app/how-to/set-up-through-the-api.md#post-the-apps-pages). Then it asks about each journey step that points at a page, action or field that's gone: retarget a rename, and drop a deleted step or leave it for you. When it changes a published journey, it asks whether to publish it again.

In Claude Code, the plugin's hooks ask Claude to run `/super-assist sync` once each time a turn changes the assisted pages. In a repository of several apps, they name the app, as in `/super-assist sync apps/web`.

The scan reads the Next.js app router and TanStack Router's file routes. Pages it doesn't read, such as those of React Router or the Next.js pages router, report themselves when end users open them. One sync sends at most 100 pages and 2,000 elements.

## Disconnect a coding agent

In the dashboard, open **Account** from your menu. **Coding agents** lists each of your connections with its client, organization and the day it connected. Press **Disconnect** beside one, and the agent's next call is refused; it signs in again to reconnect.

Owners and admins don't see other members' connections. Removing a member from the organization cuts theirs off.

## Set it up from start.md

Any coding agent, with or without the skill, can set the library up from a recipe. Paste this into the agent in your app's repo:

```txt
Read https://superassist.app/start.md then add an assistant to my app.
```

`start.md` walks it through reading your app, agreeing a plan with you, installing, getting your Super Assist project ready, adding the panel, making a first page assisted, and checking the build.

## Point an agent at the pages

- [`/llms.txt`](https://superassist.app/llms.txt) lists every page with its description, each linked as Markdown.
- [`/llms-full.txt`](https://superassist.app/llms-full.txt) holds every page in one file, for an agent that reads them all at once.
- Every page is Markdown at its URL with `.md` added. This one is [`/how-to/give-agents-the-docs.md`](https://superassist.app/how-to/give-agents-the-docs.md).

Paste a page's `.md` URL into the agent's prompt when you want it to follow that page.

---

# Set up through the API

> Install or create the agent, create the project, post the app's pages and draft journeys through the API, from a coding agent on the MCP server or with an organization key and curl.

The API does for an app what the dashboard does: it installs or creates the agent, creates the project with its publishable key, posts the app's pages to the page catalog, and drafts journeys. A coding agent connected to Super Assist's MCP server calls it as you. Without the MCP server, you or the agent call it with an organization key and curl, from the app's repository.

The commands call `https://superassist.app`. When the app's runtime sets `host` to another Super Assist origin, call that origin instead. The [API reference](https://superassist.app/docs/api) lists every route and field.

## Call the API from a coding agent

The MCP server at `https://superassist.app/mcp` lets a coding agent call the API as you, in the organization you picked when you signed in. [Connect a coding agent](https://superassist.app/how-to/give-agents-the-docs.md) installs it with the Super Assist plugin in Claude Code, or adds it by URL in Codex, Cursor and VS Code. The Super Assist skill's `setup` and `sync` commands then run this page's steps for you.

The server has two tools:

- `search` looks up a route's parameters, body and answer in the API's description.
- `execute` runs the agent's code in a sandbox whose `request({ method, path, query, body })` calls a `/api/v1` route and returns its JSON answer. A refused call throws an error naming the method, path and status, with the API's `code`, `message` and `details`.

The code is an async arrow function that returns its result, calling `codemode.request()`. One `execute` that lists the projects and reads the first one's page catalog:

```js
async () => {
  const { data } = await codemode.request({ method: "GET", path: "/api/v1/projects" });
  return codemode.request({ method: "GET", path: `/api/v1/projects/${data[0].id}/pages` });
};
```

The routes, bodies and answers are the ones below. Each `execute` can make several calls, and Claude Code shows its code before it runs. The organization key and the `curl` commands are the way in for an agent without the MCP server, or for you in a terminal.

## Put an organization key in `.env.local`

An organization key calls the API as your organization. Only owners and admins see the **API keys** page that creates one.

1. In the dashboard, open **API keys**, name the key, for example `Coding agent`, and press **Create key**.
2. Copy the key. It starts with `sa_`, and the page shows it only once.
3. Add it to `.env.local` in the app's repository, without quotes:

   ```sh title=".env.local"
   SUPER_ASSIST_API_KEY=sa_...
   ```

4. Check that git ignores the file:

   ```sh
   git check-ignore .env.local
   ```

   It prints `.env.local` when the file is ignored. When it prints nothing, add `.env.local` to `.gitignore` before you go on.

## Send the key with every command

Each command reads the key from `.env.local` and sends it as a bearer token, so the key stays out of your code, your shell history and the command's output:

```sh
key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
curl -s "https://superassist.app/api/v1/agents?limit=100" -H "Authorization: Bearer $key"
```

Keep `-v` off: it prints the `Authorization` header. A refused call answers with an error code and a message, such as:

```json
{
  "error": {
    "code": "agent_name_taken",
    "message": "An agent named \"saas-support\" already exists"
  }
}
```

`unauthorized` means the key is wrong or was revoked. A long JSON body is easier to write to a file and send with `--data-binary @file.json`.

## Pick the agent

The project needs an agent to answer. Reuse one, install a template, or create one, in that order:

1. List the organization's agents with the command above. The answer is `{ "data": [...], "nextCursor": null }`, each agent with its `id` and `name`. When one is named after the app, keep its `id` and go on to [Create the project](#create-the-project).
2. Otherwise, list the templates and install the one that fits the app. A template's id is its name:

   ```sh
   key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
   curl -s https://superassist.app/api/v1/templates -H "Authorization: Bearer $key"
   ```

   ```sh
   key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
   curl -s -X POST https://superassist.app/api/v1/templates/saas-support/install \
     -H "Authorization: Bearer $key"
   ```

   The install answers `201` with the agent, named after the template. It creates the template's skills and databases too, reusing any skill your organization already has by name. An agent or database of the same name answers `409`, and a plan limit `402`.

3. Otherwise, create an agent. Its name takes lowercase letters, numbers and single hyphens:

   ```sh
   key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
   curl -s -X POST https://superassist.app/api/v1/agents \
     -H "Authorization: Bearer $key" -H "Content-Type: application/json" \
     -d '{"name":"my-shop","description":"Helps the shop team with orders and customers.","instructions":"You help the team of My shop work through their orders and customers on the open page."}'
   ```

   It answers `201` with the agent, on the default model.

## Fill the template's placeholders

An installed template's skills carry bracketed placeholders, such as `[billing page]`, listed under the template's `placeholders` in the templates answer. [Templates](https://superassist.app/dashboard/templates.md) says what each of `saas-support`'s stands for.

1. List the skills with `GET /api/v1/skills?limit=100`, and find each placeholder in their `instructions`.
2. Replace it with what the app's repository says, and send the skill's whole instructions back:

   ```sh
   key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
   curl -s -X PATCH https://superassist.app/api/v1/skills/<skill-id> \
     -H "Authorization: Bearer $key" -H "Content-Type: application/json" \
     --data-binary @skill.json
   ```

   Here `skill.json` holds `{ "instructions": "..." }`.

3. Save the agent with an empty body, so its threads pick up the edited skills:

   ```sh
   key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
   curl -s -X PATCH https://superassist.app/api/v1/agents/<agent-id> \
     -H "Authorization: Bearer $key" -H "Content-Type: application/json" -d '{}'
   ```

Leave a placeholder the repository doesn't answer, and note it for whoever finishes in the dashboard.

## Create the project

Create the project with the agent as its default and the origins the app runs on in development:

```sh
key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
curl -s -X POST https://superassist.app/api/v1/projects \
  -H "Authorization: Bearer $key" -H "Content-Type: application/json" \
  -d '{"name":"My shop","defaultAgentId":"<agent-id>","allowedOrigins":["http://localhost:3000"]}'
```

`allowedOrigins` replaces the default list, so name every origin. Left out, the project allows `http://localhost:3000` and `http://localhost:5173`. The answer is `201` with the project:

```json
{
  "id": "7c1e4b0a-…",
  "name": "My shop",
  "description": null,
  "publishableKey": "pk_…",
  "allowedOrigins": ["http://localhost:3000"],
  "defaultAgentId": "<agent-id>",
  "createdBy": null,
  "createdAt": "2026-11-01T10:00:00.000Z",
  "updatedAt": "2026-11-01T10:00:00.000Z"
}
```

Write `publishableKey` to the app's public variable in `.env.local`, such as `NEXT_PUBLIC_SUPER_ASSIST_KEY` for Next.js or `VITE_SUPER_ASSIST_KEY` for Vite. Unlike the organization key, it ships in the app's bundle. [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md) connects the app with it.

When the app already has a project, find its `id` in `GET /api/v1/projects`, by the `publishableKey` the app uses.

## Post the app's pages

The page catalog holds the app's pages for the journey editor's pickers. Pages report themselves once the app runs; posting them now puts the whole sitemap in the catalog from the start. Send one entry per `destinations` path, with the page's name, its instructions, and the actions and fields it lends:

```sh
key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
curl -s -X POST https://superassist.app/api/v1/projects/<project-id>/pages \
  -H "Authorization: Bearer $key" -H "Content-Type: application/json" \
  --data-binary @pages.json
```

```json title="pages.json"
{
  "pages": [
    {
      "path": "/orders",
      "name": "Orders",
      "instructions": "Every order of the shop. Ship or cancel an order that is waiting to ship by its id.",
      "elements": [
        { "name": "new_order", "kind": "action", "label": "Open the New order dialog" },
        { "name": "ship_order", "kind": "action", "byId": true }
      ]
    },
    {
      "path": "/orders/:id",
      "name": "Order",
      "elements": [
        { "name": "note", "kind": "field", "label": "The order's note" },
        { "name": "save_note", "kind": "action", "label": "Save the note" }
      ]
    }
  ]
}
```

- `byId: true` marks a name that rows lend, each with its own `id`. It keeps no label.
- A page sent without `instructions` keeps those it has.
- One request takes 1 to 100 pages and at most 2,000 elements.

The answer is the whole catalog, `{ "data": [...] }`, and the project's **Pages** tab shows it.

A post only adds and updates. Once the app's routes change, add `"replace": true` beside `pages` and send every page the code has: the catalog then keeps only what you sent. The Super Assist skill's `sync` command builds that body from the code and sends it. Pages you left out go with their elements, those the app reported itself included, and so do the elements a page you sent leaves out. When a page you dropped by mistake still lends something, the app reports it back the next time an end user opens it.

## Draft journeys

A journey walks end users through the app toward a goal, one step at a time. Start with up to three, each of three or four steps, built from the app's routes and what its pages lend:

```sh
key=$(sed -n 's/^SUPER_ASSIST_API_KEY=//p' .env.local)
curl -s -X POST https://superassist.app/api/v1/projects/<project-id>/journeys \
  -H "Authorization: Bearer $key" -H "Content-Type: application/json" \
  --data-binary @journey.json
```

```json title="journey.json"
{
  "name": "ship-an-order",
  "goal": "A new team member ships an order and leaves a note on it.",
  "trigger": "manual",
  "steps": [
    {
      "path": "/orders",
      "title": "Your orders",
      "body": "Every order of the shop is listed here."
    },
    {
      "path": "/orders",
      "element": { "kind": "action", "name": "ship_order" },
      "title": "Ship an order",
      "body": "Press Ship on an order that is waiting to ship."
    },
    {
      "path": "/orders/:id",
      "element": { "kind": "field", "name": "note" },
      "title": "Leave a note",
      "body": "Each order keeps a note for your team."
    },
    {
      "path": "/orders/:id",
      "element": { "kind": "action", "name": "save_note" },
      "title": "Save it"
    }
  ]
}
```

- `name` follows the same rule as an agent's and is unique in the project.
- A step's `path` is a `destinations` path, and its optional `element` is an action or field that page lends, by its lent name. The API doesn't check either against the catalog, so take them from the pages you posted.
- A journey has 1 to 10 steps. A `title` takes up to 120 characters, a `body` up to 1,000.
- `manual` starts the journey only from host code or a link. `page` starts it once per end user on its first step's page. A member can change it before publishing.

The answer is `201` with the journey, its `state` `draft` and its `publishedSteps` `null`: end users see nothing of it yet. A name already taken answers `409` `journey_name_taken`. To change a draft, send the changed fields to `PATCH /api/v1/projects/<project-id>/journeys/<journey-id>`.

## Publish the journeys

Only a member publishes a journey. A coding agent on the MCP server acts as you, so it can publish a draft once you say so, with `POST /api/v1/projects/<project-id>/journeys/<journey-id>/publish`. The same route answers an organization key with `403`: on the project's **Journeys** page, set each draft's trigger and publish it.

The key stays in `.env.local` for later drafts. When you no longer need it, press **Revoke** beside it on **API keys**.

---

# Make a page assisted

> Introduce a page or a dialog to the assistant with AssistedPage.

Wrap the page's content in `AssistedPage` inside a client component under `AssistedProvider`.

## Wrap the page

Give it three things:

- `name`: what the user calls the page. The panel's header shows it.
- `instructions`: how to work there, in a few sentences. Name the page's tools and actions where they help.
- `content`: a function returning what the page shows, as plain data. The assistant reads it through `get_page_content` when it needs it.

From `examples/app/app/page.tsx`:

```tsx
    <AssistedPage
      name="Dashboard"
      instructions="The shop's overview: orders waiting to ship, open refunds, revenue this month and the latest orders. Orders, customers and settings each have a page of their own, and so does every order."
      content={() => ({
        toShip: toShip.map(row),
        openRefunds: openRefunds.map(row),
        revenueThisMonth: money(revenue),
        latest: latest.map(row),
      })}
    >
```

Return ids and values the assistant can act on. The universal instructions tell it to take every id and value from `get_page_content`'s answer.

## Name a page from its data

`name` and `instructions` take a string or a function. Each is read when the note is built. From `examples/app/app/orders/[id]/page.tsx`:

```tsx
    <AssistedPage
      name={`Order #${id}`}
      instructions="One order: its customer, items, total, status, refund and note. note fills the note field without saving it, and save_note saves what the field holds."
      content={() => (row ? { ...row, note: order!.note, noteField: draft } : `No order #${id}.`)}
    >
```

## Suggest first messages

`starters` lists first messages for the panel's empty state on this page. Each shows as a button, and picking one sends it as typed. From `examples/app/app/settings/page.tsx`:

```tsx
    <AssistedPage
      name="Settings"
      starters={["Change the shop name to Northwind Traders", "What does each setting do?"]}
      instructions="The shop's name, currency and notification email. setting fills one field by its id without saving; Save saves the form."
      content={() => ({ saved: shop.settings, form: draft, error })}
    >
```

A page without `starters` shows the provider's `starters`, for every page at once:

```tsx
<AssistedProvider runtime={runtime} starters={["What can you do on this page?"]}>
```

Write starters the page can answer: each names something on it.

## Make a dialog assisted

A dialog over a page is an assisted page of its own. Put `AssistedPage` inside the dialog's content. While the dialog is mounted it is the page the user has open, because the last mounted page wins. When it closes, the page under it is back.

Make the dialog non-modal. A modal backdrop covers the panel, so the user cannot type to the assistant while the dialog is open. From `examples/app/app/orders/new-order.tsx`:

```tsx
export function NewOrder({
  open,
  onOpenChange,
}: {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}) {
  return (
    <Dialog open={open} onOpenChange={onOpenChange} modal={false} disablePointerDismissal>
      <DialogContent showOverlay={false}>
        <NewOrderPage close={() => onOpenChange(false)} />
      </DialogContent>
    </Dialog>
  );
}

function NewOrderPage({ close }: { close: () => void }) {
  const [draft, setDraft] = useState(blank);
  const [error, setError] = useState<string>();
  return (
    <AssistedPage
      name="New order"
      instructions="A dialog over Orders for a new order. Fill its fields with order_field by id, then save_order creates the order and closes the dialog; cancel closes it without saving."
      content={() => ({ ...draft, error })}
    >
```

`showOverlay` is a prop of the example's own `dialog.tsx`. Use your dialog's way of dropping the backdrop.

## Check it

Open the panel on the page. In the floating and sheet modes, its header reads "On" and the page's name, such as "On Dashboard". In the devtools' **Assisted pages** tab, the note and `get_page_content`'s answer show what the assistant receives. See [Mount the devtools](https://superassist.app/how-to/mount-devtools.md).

---

# Add actions and group row actions

> Let the assistant press things on the page with AssistedAction, one per element or one per row.

An assisted action is a thing on an assisted page the assistant presses as the user would click it. Render it inside an `AssistedPage`. Outside one, it throws.

## Wrap one element

Wrap the element in `AssistedAction` with a `name` and a `label`. The label says what pressing does. From `examples/app/app/orders/page.tsx`:

```tsx
<AssistedAction name="new_order" label="Open the New order dialog">
  <Button size="sm" className="ms-auto" onClick={() => setCreating(true)}>
    New order
  </Button>
</AssistedAction>
```

`AssistedAction` takes one child and attaches a ref to it. The child must pass that ref to a DOM element. shadcn's `Button` does.

A press answers with `Pressed "<label>".` and the page's note as the press left it.

## Group row actions

Give every row the same `name` and its own `id`. The assistant sees one tool that picks a row by id, and the ids follow the rows as they mount and unmount. From `examples/app/app/orders/page.tsx`:

```tsx
<AssistedAction
  name="ship_order"
  id={order.id}
  label={`Ship ${order.customer}'s order #${order.id}`}
>
  <Button size="sm" onClick={() => shop.call("shipOrder", [order.id])}>
    Ship
  </Button>
</AssistedAction>
```

Use ids the page's content also returns, so the assistant can match a row it read to the row it presses. In a group, give every row an `id`.

## Let disabled mean disabled

A press checks the element first. A native `disabled` or `aria-disabled="true"` answers that the action is disabled right now, and nothing is clicked. From `examples/app/app/orders/[id]/page.tsx`:

<!-- prettier-ignore -->
```tsx
<AssistedAction name="save_note" label="Save the note">
  <Button
    disabled={draft === order.note}
    onClick={() => shop.call("saveNote", [order.id, draft])}
  >
    Save note
  </Button>
</AssistedAction>
```

## Use the hook instead

When wrapping does not fit, call `useAssistedAction` and attach the ref it returns:

```tsx
export function ShipButton({ id, onShip }: { id: string; onShip: () => void }) {
  const ref = useAssistedAction<HTMLButtonElement>({
    name: "ship_order",
    id,
    label: `Ship order #${id}`,
  });
  return (
    <button ref={ref} onClick={onShip}>
      Ship
    </button>
  );
}
```

To have the user press it instead, see [Make an action consequential](https://superassist.app/how-to/make-an-action-consequential.md).

---

# Lend a form's fields

> Let the assistant fill a page's inputs, selects and switches with AssistedInput, or any control with AssistedField.

An assisted field is a field on an assisted page the assistant fills as the user would type into it. Each field is a tool of its name, and the page's note shows what each field says now. Render it inside an `AssistedPage`. Outside one, it throws.

A fill changes the form, not your data. Keep saving on the page's own button, lent as an [action](https://superassist.app/how-to/add-actions.md).

## Wrap a field

Wrap the input, textarea, native select, checkbox or switch in `AssistedInput` with a `name` and a `label`. The label says what the field holds. From `examples/app/app/orders/[id]/page.tsx`:

```tsx
<AssistedInput name="note" label="The order's note">
  <Textarea value={draft} onChange={(event) => setDraft(event.target.value)} />
</AssistedInput>
```

`AssistedInput` takes one child and attaches a ref to it. The child must pass that ref to the field's DOM element. shadcn's `Input`, `Textarea` and `NativeSelect` do.

A fill writes through the element's own value setter and fires an `input` event, so your `onChange` runs as if the user typed. Uncontrolled forms see the new value too. Once the page has rendered, the fill answers `Filled "<label>"; it now says <value>.`

## Group a form's fields by id

Give every field the same `name` and its own `id`. The assistant sees one tool that fills a field by id. From `examples/app/app/settings/page.tsx`:

<!-- prettier-ignore -->
```tsx
{fields.map(([field, id, label]) => (
  <Label key={field} className="grid gap-1.5">
    {label}
    <AssistedInput name="setting" id={id} label={label}>
      <Input value={draft[field]} onChange={(event) => set(field, event.target.value)} />
    </AssistedInput>
  </Label>
))}
```

The page's note then lists the group with each field's value:

```md
Its fields: setting (name: Shop name, now "Northwind"; currency: Currency, now "USD"; email: Notification email, now "alerts@northwind.example").
```

Say in the page's `instructions` which action saves the form, so the assistant fills and then saves.

## Know what each field takes

`AssistedInput` reads the wrapped element when it mounts and fills it by its kind:

| Child                        | A fill                                                  | The note shows                  |
| ---------------------------- | ------------------------------------------------------- | ------------------------------- |
| `<input>`, `<textarea>`      | Sets the value, fires `input`                           | The text, cut at 200 characters |
| `<input type="password">`    | Sets the value, fires `input`                           | `(filled)` or `(empty)`         |
| Checkbox, or `role="switch"` | Clicks it when it is not already `on` or `off` as asked | `on` or `off`                   |
| `<select>`                   | Sets the value, fires `change`                          | The selected value              |
| Anything else                | Rings it for the user                                   | Its text                        |

A select's options become the only values its tool takes, read from the DOM when the field mounts. A switch or checkbox takes `on` and `off`.

## Leave a field to the user

Pass `consequential` when the user should type the value themselves. A call then rings the field and answers that filling it is theirs:

```tsx
<AssistedInput name="email" label="Your email" consequential>
  <Input type="email" name="email" />
</AssistedInput>
```

A disabled or read-only field answers that it is disabled or read-only right now, and nothing changes.

## Lend a control that is not a native field

A custom control keeps its value in state, not in a DOM field. Lend it with `AssistedField`, which takes the value and a function that fills it. `options` lists the only values it takes:

```tsx
const plans = [
  { value: "free", label: "Free" },
  { value: "pro", label: "Pro" },
];

export function PlanPicker({ plan, setPlan }: { plan: string; setPlan: (plan: string) => void }) {
  return (
    <AssistedField name="plan" label="Billing plan" options={plans} value={plan} onFill={setPlan}>
      <div role="radiogroup" aria-label="Billing plan">
        {plans.map((option) => (
          <button
            key={option.value}
            type="button"
            role="radio"
            aria-checked={plan === option.value}
            onClick={() => setPlan(option.value)}
          >
            {option.label}
          </button>
        ))}
      </div>
    </AssistedField>
  );
}
```

The child is only the ring target. `onFill` gets the value the assistant chose, and the answer shows `value` once the page has rendered.

## Use the hook instead

When wrapping does not fit, call `useAssistedInput` and attach the ref it returns:

```tsx
export function CouponInput() {
  const ref = useAssistedInput<HTMLInputElement>({ name: "coupon", label: "Coupon code" });
  return <input ref={ref} name="coupon" />;
}
```

## Check it

Open the devtools' **Assisted pages** tab. The **Fields** list shows each field tool with what every field says now. See [Mount the devtools](https://superassist.app/how-to/mount-devtools.md).

---

# Make an action consequential

> Have the assistant ring an action for the user to press, or ask in the panel before it presses.

A consequential action is one whose effect the user should own. Pick one of two shapes with the `consequential` prop.

## Ring it for the user to press

Pass `consequential`. When the assistant calls the action, the element is scrolled into view with a ring around it and the label above or below it. The user presses it, or dismisses the ring. From `examples/app/app/orders/[id]/page.tsx`:

```tsx
<AssistedAction name="refund_order" label="Refund this order" consequential>
  <Button
    variant="destructive"
    disabled={!refundable}
    onClick={() => shop.call("refundOrder", [order.id])}
  >
    Refund
  </Button>
</AssistedAction>
```

The model sees the action marked "(consequential)". Its call answers `Rang "<label>" for the user; pressing it is theirs.` A disabled or missing element answers so, and nothing rings.

## Ask in the panel, then press

Pass `consequential="confirm"`. When the assistant calls the action, the panel shows a card with the label and **Approve** and **Deny**. On approval the action is pressed. A denial is final for that call. From `examples/app/app/orders/page.tsx`:

<!-- prettier-ignore -->
```tsx
<AssistedAction
  name="cancel_order"
  id={order.id}
  label={`Cancel ${order.customer}'s order #${order.id}`}
  consequential="confirm"
>
  <Button
    size="sm"
    variant="outline"
    onClick={() => shop.call("cancelOrder", [order.id])}
  >
    Cancel
  </Button>
</AssistedAction>
```

The model sees the action marked "(asks first)". In a group, the card asks about the one row the assistant picked. The element is checked again after approval, in case it left or became disabled while the card waited.

The card is the package's [confirm card](https://superassist.app/components/cards/confirm-card.md). After the answer it stays in the conversation as a receipt: Finished or Denied. To render it your own way, see [Swap a card](https://superassist.app/how-to/swap-a-card.md).

## Ask before a tool runs

A tool has no element to ring. `consequential: true` on `useAssistedTool` asks in the panel and runs `execute` only on approval:

```tsx
export function Refund({ refund }: { refund: () => Promise<void> }) {
  useAssistedTool("refund_order", {
    description: "Refund this order.",
    parameters: { type: "object", properties: {} },
    consequential: true,
    execute: async () => {
      await refund();
      return "Refunded the order.";
    },
  });
  return null;
}
```

The card shows the tool's description.

## Ring an element from your own code

`useRing` returns a function that rings an element. The ring leaves when the component unmounts:

```tsx
export function WhereToSave() {
  const ringAt = useRing();
  const save = useRef<HTMLButtonElement>(null);
  return (
    <>
      <Button ref={save}>Save</Button>
      <Button
        variant="ghost"
        onClick={() => save.current && ringAt(save.current, { message: "Save is here" })}
      >
        Where do I save?
      </Button>
    </>
  );
}
```

`ring(element, { message })` does the same outside React and returns a function that dismisses it.

---

# Lend a tool

> Lend the assistant a tool with useAssistedTool, scoped to a page or global.

A tool is a capability beyond pressing an action: reading or changing what the page shows, or going elsewhere. It runs in the browser. Lend one with `useAssistedTool(name, { description, parameters, execute })`.

## Lend it on a page

Call `useAssistedTool` in a component rendered under the `AssistedPage`. The tool belongs to the page: the page's note lists it, and it leaves with the page. From `examples/app/app/orders/page.tsx`:

```tsx
useAssistedTool("filter_orders", {
  description: "Show only the orders with one status, or all of them.",
  parameters: {
    type: "object",
    properties: { status: { type: "string", enum: filters } },
    required: ["status"],
  },
  execute: ({ status }: { status: Filter }) => {
    setFilter(status);
    return `Showing ${status === "all" ? "all orders" : `the orders that are ${status}`}.`;
  },
});
```

## Split the page in two

The tool's hook must render under the `AssistedPage`, while `content` needs the same state. So a page with tools is two components: the state and the `AssistedPage` above, the tools below. From `examples/app/app/orders/page.tsx`:

```tsx
export default function Orders() {
  const shop = useShop();
  const [filter, setFilter] = useState<Filter>("all");
  const money = moneyOf(shop.settings.currency);
  const rows = shop.orders
    .filter((order) => filter === "all" || order.status === filter)
    .map((order) => rowOf(order, money));
  return (
    <AssistedPage
      name="Orders"
      instructions="Every order of the shop, as filtered by status with filter_orders, and charted by status with chart_orders. Ship or cancel an order that is waiting to ship by its id. New order opens a dialog that introduces itself. Each order has a page of its own with its note and refund."
      content={() => ({ filter, orders: rows })}
    >
      <OrdersTable filter={filter} setFilter={setFilter} rows={rows} />
    </AssistedPage>
  );
}
```

`OrdersTable` lends `filter_orders`, shown above.

## Lend it everywhere

Call `useAssistedTool` outside any `AssistedPage`, under `AssistedProvider`. The tool is global: it works from every page and no note lists it. From `examples/app/app/shell.tsx`:

```tsx
useAssistedTool("get_shop_summary", {
  description: "How many orders and customers the shop has. Works from any page.",
  parameters: { type: "object", properties: {} },
  execute: () => ({ orders: shop.orders.length, customers: shop.customers.length }),
});
```

## Describe the parameters

`parameters` takes a JSON Schema object or a Standard Schema such as a zod schema. With JSON Schema, type the arguments of `execute` yourself, as above. With zod, they are inferred:

```tsx
const refund = z.object({ id: z.string().describe("The order's id.") });

export function RefundTool({ refundOrder }: { refundOrder: (id: string) => Promise<void> }) {
  useAssistedTool("refund_order", {
    description: "Refund an order.",
    parameters: refund,
    execute: async ({ id }) => {
      await refundOrder(id);
      return `Refunded ${id}.`;
    },
  });
  return null;
}
```

Define the schema at module scope.

The tool is lent again when its description or its parameters' JSON Schema changes. `execute` always runs the latest closure.

## Let failures speak

Throw from `execute` when the tool cannot do its job. The model gets `{ error: "<name> failed: <message>" }` and the turn goes on. Arguments the schema rejects answer with an `{ error }` too.

## Show the model an image

`toModelOutput` replaces what the model sees with text and file parts, while the result stays what the thread shows. From `examples/app/app/orders/page.tsx`, a tool that draws the orders by status on a canvas and hands the model the PNG:

```tsx
useAssistedTool("chart_orders", {
  description: "A bar chart of the shop's orders by status, as an image.",
  parameters: { type: "object", properties: {} },
  execute: () => {
    const counts = statuses.map((status) => [status, countOf(status)] as const);
    return { counts: Object.fromEntries(counts), png: barChart(counts) };
  },
  toModelOutput: ({ output }) => [
    { type: "text", text: `Orders by status: ${JSON.stringify(output.counts)}` },
    { type: "file", data: output.png, mediaType: "image/png", filename: "orders.png" },
  ],
});
```

`data` is base64. Up to 4 files of 5 MB each; more answers with an `{ error }`. Images show under the call in the thread. A model that takes no files gets the text and a line counting the files it missed.

## Show a card for the call

`render` takes a tool UI component for the tool's calls in the thread. Define it at module scope, so the same component is passed on every render.

To ask the user before the tool runs, see [Make an action consequential](https://superassist.app/how-to/make-an-action-consequential.md#ask-before-a-tool-runs).

---

# Add go_to_page

> Let the assistant open other pages of the app and show links to them.

Pass `destinations` and `navigate` to `AssistedProvider`. With both, the provider lends `go_to_page` and `show_links`. Without either, it lends neither.

## Name the pages

`destinations` maps a page's name to its path. A path with `:id` takes an id. From `examples/app/app/assistant.tsx`:

```tsx
const destinations = {
  home: "/",
  orders: "/orders",
  order: "/orders/:id",
  customers: "/customers",
  settings: "/settings",
};
```

Define it at module scope, as the example does.

## Pass the router

`navigate` opens a path. In Next.js it is `router.push`. From `examples/app/app/assistant.tsx`:

```tsx
    <AssistedProvider
      runtime={runtime}
      destinations={destinations}
      navigate={(path) => router.push(path)}
    >
```

## What the assistant gets

- `go_to_page({ to, id? })` calls `navigate`, waits up to 5 seconds for the assisted page to change, and answers `Opened <path>.` with the note of the page now open.
- `show_links({ items })` shows a card of links, each a destination with a title and a one-line gist. A click calls `navigate`.

## Keep the paths out of the description

`go_to_page`'s description lists every destination and its path. When the app's own instructions, like a skill, own its pages, the model answers from that list instead. Pass `destinationsDescription` to say something else in its place:

```tsx
<AssistedProvider
  runtime={runtime}
  destinations={destinations}
  destinationsDescription="Activate the product skill for the page names."
  navigate={(path) => router.push(path)}
>
```

The `to` parameter still lists every destination name, so a call stays valid.

The universal instructions tell the assistant to use `go_to_page` when the user asks to go somewhere or the work is on another page. The answers and errors are in the [model context reference](https://superassist.app/reference/model-context.md#built-in-tools).

---

# Place the panel

> Render AssistedPanel floating, as a sheet or embedded, size its window, and open it from a launcher, your own trigger or code.

`AssistedPanel` renders inside `AssistedProvider` and picks where it shows with `mode`. Import the styles once, anywhere in the app:

```tsx
import "@super-assist/react/styles.css";
```

## Pick a mode

Each branch below is from `examples/app/app/assistant.tsx`, which switches mode on a query parameter in development.

**Floating**: a window over the page that the user drags, resizes, minimizes and maximizes. While it is closed, a launcher button in the corner opens it.

```tsx
return (
  <>
    <main className="min-h-dvh p-6">{children}</main>
    <AssistedPanel mode="floating" />
  </>
);
```

**Sheet**: a column beside the page that takes the page's space, with no overlay. Closed, it is a slim rail with a button. Put it in a flex row with the page:

```tsx
return (
  <div className="flex h-dvh">
    <main className="min-w-0 flex-1 overflow-y-auto p-6">{children}</main>
    <AssistedPanel mode="sheet" />
  </div>
);
```

**Embedded**: the conversation and the composer, placed where your layout puts them. It has no header and no launcher, and it is always shown. Give its container a height:

```tsx
return (
  <div className="flex h-dvh">
    <main className="min-w-0 flex-1 overflow-y-auto p-6">{children}</main>
    <div className="w-md shrink-0 border-s">
      <AssistedPanel mode="embedded" />
    </div>
  </div>
);
```

## Name it

`title` and `icon` replace "Assistant" and the logo in the header and on the launcher. `description` is the header's line when no assisted page is open:

```tsx
<AssistedPanel
  mode="floating"
  title="Shop assistant"
  icon={<ShoppingBag />}
  description="Ask about anything in the shop."
/>
```

## Size the floating window

The floating window opens 420 by 640 px in the bottom-right corner, 24 px in. `defaultPosition` and `defaultSize` change where and how big it first opens. The user's moves and resizes persist across opens.

```tsx
<AssistedPanel
  mode="floating"
  defaultPosition="bottom-left"
  defaultSize={{ width: 480, height: 720 }}
/>
```

`resizable={false}`, `draggable={false}` and `windowControls={false}` turn off its edge handles, its dragging by the header, and its Minimize and Maximize buttons. Close stays.

## Open it from your chrome

`AssistedPanel.Trigger` is a small Assistant button for your own toolbar. It opens and closes the floating window or the sheet. From `examples/app/app/shell.tsx`:

```tsx
<div className="ms-auto flex gap-2">
  {mode !== "embedded" && <AssistedPanel.Trigger />}
  <Button variant="outline" size="sm" onClick={() => shop.call("reset")}>
    Reset shop
  </Button>
</div>
```

With `asChild`, your own button becomes the trigger. Pass `launcher={false}` when the trigger is the only way in:

```tsx
<AssistedPanel mode="floating" launcher={false} />

<AssistedPanel.Trigger asChild>
  <Button>Help</Button>
</AssistedPanel.Trigger>
```

The trigger may sit anywhere inside `AssistedProvider`, outside the panel.

## Open it from code

`useAssisted` opens and closes the panel. `open` with a message also sends it as the user's:

```tsx
export function AskAboutOrder({ id }: { id: string }) {
  const { open } = useAssisted();
  return (
    <Button onClick={() => open(`Why hasn't order #${id} shipped?`)}>Ask the assistant</Button>
  );
}
```

## Keep host dialogs out of the way

The floating panel sits at z-index 50, above the ring. A modal dialog's backdrop still blocks it. Make assisted dialogs non-modal, see [Make a dialog assisted](https://superassist.app/how-to/make-a-page-assisted.md#make-a-dialog-assisted).

Every prop is on [Roots and window](https://superassist.app/components/panel/roots-and-window.md#props). To change what the panel holds, see [Rearrange the panel's parts](https://superassist.app/how-to/rearrange-the-panel.md).

---

# Rearrange the panel's parts

> Compose AssistedPanel from its parts to move, swap or leave out the header, the threads, the conversation, the composer and the data parts.

The one-liner renders the default composition. To change what the panel holds, render a root with the parts you want as its children. Every container with no children renders its own default, so you only spell out the level you change.

A root lays its children out in a row: `Threads`, the thread list in a column of its own, and `Main`, the column that holds the header, the conversation, the composer and the footer. Leave `Threads` out and `Main` takes the whole width.

The five panels below run in the example's panel playground, `examples/app/components/panel-playground.tsx`.

## Start from the one-liner

```tsx
<AssistedPanel mode="floating" threads models={models} />
```

This is the default composition. Every prop it takes is a root prop, so the rest of this page can keep it.

## Spell out the top level

Render a root with `Main` and its three containers. Each renders its default, so this panel looks like the one-liner, opened in the bottom-left corner:

```tsx
<AssistedPanel.Floating defaultPosition="bottom-left">
  <AssistedPanel.Main>
    <AssistedPanel.Main>
      <AssistedPanel.Header />
      <AssistedPanel.Conversation />
      <AssistedPanel.Composer />
    </AssistedPanel.Main>
  </AssistedPanel.Main>
</AssistedPanel.Floating>
```

Leave a part out and it is gone. Reorder them and they move.

## Put the threads beside the conversation

`Threads` is the thread list in a column before `Main`, for a panel wide enough to show both. The one-liner places it with `threads="side"`:

```tsx
<AssistedPanel.Embedded threads="side" models={models} />
  <AssistedPanel.Main>
```

Spelled out, the same panel is a root with the two columns:

```tsx
<AssistedPanel.Embedded models={models}>
  <AssistedPanel.Threads />
  <AssistedPanel.Main />
</AssistedPanel.Main>
</AssistedPanel.Embedded>
```

## Write your own header

Give `Header` children and it renders exactly those. This sheet names the shop's assistant, keeps the devtools and Close, and puts the thread select in a row of its own:

```tsx
<AssistedPanel.Sheet>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.Icon>
        <ShopLogo />
      </AssistedPanel.Icon>
      <AssistedPanel.Title>Shop assistant</AssistedPanel.Title>
      <AssistedPanel.Devtools>
        <AssistedDevtoolsPanel />
      </AssistedPanel.Devtools>
      <AssistedPanel.Close />
    </AssistedPanel.Header>
    <AssistedPanel.ThreadSelect />
    <AssistedPanel.Conversation />
    <AssistedPanel.Composer />
  </AssistedPanel.Main>
</AssistedPanel.Sheet>
```

## Add the data parts and trim the composer

Any part may sit in any container under a root. This embedded panel shows the context window in its header and footer, swaps the conversation for settings, and keeps three parts of the composer:

```tsx
<AssistedPanel.Embedded models={models}>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.Title />
      <AssistedPanel.ContextDisplay />
      <AssistedPanel.SettingsToggle />
    </AssistedPanel.Header>
    <AssistedPanel.SettingsPanel>
      <AssistedPanel.ContextBreakdown />
      <AssistedPanel.QuotaBanner
        used={42}
        limit={50}
        unit="messages"
        resetsIn="3h"
        upgradeLabel="Upgrade"
      />
    </AssistedPanel.SettingsPanel>
    <AssistedPanel.Conversation>
      <AssistedPanel.ConversationSearch />
      <AssistedPanel.Messages components={{ AssistantMessage: Mine }} />
      <AssistedPanel.ScrollToBottom />
    </AssistedPanel.Conversation>
    <AssistedPanel.Composer>
      <AssistedPanel.Input />
      <AssistedPanel.ModelSelector />
      <AssistedPanel.Send />
    </AssistedPanel.Composer>
    <AssistedPanel.Footer>
      <AssistedPanel.ContextDisplay variant="bar" className="flex-1" />
    </AssistedPanel.Footer>
  </AssistedPanel.Main>
</AssistedPanel.Embedded>
```

`Messages` takes `components` for what happens inside a message. `Mine` is the example's own assistant message, built from `MessagePrimitive`:

```tsx
function Mine() {
  return (
    <MessagePrimitive.Root className="rounded-lg border-s-2 border-teal-600 bg-teal-50 px-3 py-2 text-sm">
      <MessagePrimitive.Parts />
    </MessagePrimitive.Root>
  );
}
```

## Use your own buttons and trigger

A button part with `asChild` renders your element and keeps its behavior. This floating panel opens a thread drawer from the header with the host's icon buttons, and opens only from a trigger the host places:

```tsx
<>
  <AssistedPanel.Floating launcher={false}>
    <AssistedPanel.Main>
      <AssistedPanel.Header>
        <AssistedPanel.ThreadDrawerToggle asChild>
          <IconButton icon={PanelLeft} />
        </AssistedPanel.ThreadDrawerToggle>
        <AssistedPanel.ThreadTitle />
        <AssistedPanel.NewThread asChild>
          <IconButton icon={Plus} />
        </AssistedPanel.NewThread>
        <AssistedPanel.Close />
      </AssistedPanel.Header>
      <AssistedPanel.ThreadDrawer />
      <AssistedPanel.Conversation />
      <AssistedPanel.Composer />
    </AssistedPanel.Main>
  </AssistedPanel.Floating>
  <nav className="fixed start-1/2 bottom-6 z-40 -translate-x-1/2">
    <AssistedPanel.Trigger asChild>
      <Button>Help</Button>
    </AssistedPanel.Trigger>
  </nav>
</>
```

`IconButton` is the example's own button. `asChild` hands it the part's `onClick`, `aria-label` and `aria-pressed`.

## Rules of the parts

- Render parts inside a root. The root holds the panel's state: open, the picked model, the drawer, the search and the settings.
- A root is a row of `Threads` and `Main`. The header, the conversation, the composer and the footer go in `Main`.
- A container with no children renders its default. With children, it renders only those.
- Parts that have nothing to show render nothing: `ModelSelector` without `models`, `Devtools` without devtools, `Footer` without children.
- `Trigger` is the one part that may sit outside a root, anywhere under `AssistedProvider`.

Each group's parts, props and default are on its page under [Components](https://superassist.app/components.md#panel). To replace a part with your own, see [Make your own part](https://superassist.app/how-to/make-your-own-part.md).

---

# Make your own part

> Replace a part of the panel with your own component, built on useAssisted, useAui, useAuiState and the primitives, and drop it where the part went.

A part of your own is a component that reads the panel's state and acts on it. Build it on what `@super-assist/react` exports, then render it where the part it replaces went.

## Read and drive the panel

`useAssisted` gives the panel's open state and the open page's name:

```tsx
import { useAssisted } from "@super-assist/react";

function PageBadge() {
  const { page } = useAssisted();
  if (!page) return null;
  return <span className="rounded bg-muted px-1.5 text-xs">{page}</span>;
}
```

It also returns `isOpen`, `open(message?)` and `close()`.

## Read and drive the thread

`useAuiState` selects from the runtime's state and re-renders when the selection changes. `useAui` returns the client that acts on it:

```tsx
import { useAui, useAuiState } from "@super-assist/react";

function StartOver() {
  const aui = useAui();
  const running = useAuiState((s) => s.thread.isRunning);
  return (
    <button disabled={running} onClick={() => aui.threads.switchToNewThread()}>
      Start over
    </button>
  );
}
```

`s.thread` holds the open thread: `messages`, `isRunning`. `s.threads` holds the list: `threadIds`, `threadItems`, `mainThreadId`. `aui.threads` switches, starts and deletes threads. `useAuiEvent` subscribes to the runtime's events.

## Build on the primitives

The primitives are unstyled components with the panel's behavior: `ComposerPrimitive`, `ThreadPrimitive`, `MessagePrimitive`, `ActionBarPrimitive`, `BranchPickerPrimitive`, `AttachmentPrimitive`, `ErrorPrimitive`, `SuggestionPrimitive`, `ThreadListPrimitive` and `ThreadListItemPrimitive`. Style them with your own classes. A composer of your own:

```tsx
import { ComposerPrimitive } from "@super-assist/react";

function PlainComposer() {
  return (
    <ComposerPrimitive.Root className="flex gap-2 border-t p-2">
      <ComposerPrimitive.Input className="flex-1 bg-transparent" placeholder="Ask the shop…" />
      <ComposerPrimitive.Send className="rounded bg-primary px-3 text-primary-foreground">
        Send
      </ComposerPrimitive.Send>
    </ComposerPrimitive.Root>
  );
}
```

A part you replace takes its behavior with it. `PlainComposer` has no slash commands, which belong to `AssistedPanel.Input`.

## Drop it where the part went

Render the parts around it as before. Your components sit beside them:

```tsx
<AssistedPanel.Floating>
  <AssistedPanel.Main>
    <AssistedPanel.Header>
      <AssistedPanel.Icon />
      <AssistedPanel.Title />
      <PageBadge />
      <StartOver />
      <AssistedPanel.Close />
    </AssistedPanel.Header>
    <AssistedPanel.Conversation />
    <PlainComposer />
  </AssistedPanel.Main>
</AssistedPanel.Floating>
```

Inside a root, your component sits inside the panel's scoped styles and the runtime's context. Outside one, under `AssistedProvider`, `useAssisted`, `useAui` and `useAuiState` still work.

## Replace a message

Parts end where a single message begins. To change how a message looks, pass a component to `Messages`' `components`, built from `MessagePrimitive`:

```tsx
function Mine() {
  return (
    <MessagePrimitive.Root className="rounded-lg border-s-2 border-teal-600 bg-teal-50 px-3 py-2 text-sm">
      <MessagePrimitive.Parts />
    </MessagePrimitive.Root>
  );
}

<AssistedPanel.Conversation>
  <AssistedPanel.Messages components={{ AssistantMessage: Mine }} />
</AssistedPanel.Conversation>;
```

The slots are listed on [Conversation](https://superassist.app/components/panel/conversation.md#props). To change how a tool's call shows, see [Swap a card](https://superassist.app/how-to/swap-a-card.md).

## Reuse the panel's pieces

The pieces the parts are built from are exported too, for a part that keeps their look: `ThreadList`, `ModelSelector`, `EmptyState` with `EmptyStateGreeting`, `EmptyStateSuggestions` and `EmptyStateSuggestion`, `ConversationSearch`, `ThreadSearch`, `StoppedRun`, `SettingsPanel`, `ContextBreakdown`, `QuotaBanner`, `LauncherBubble`, `Suggestions`, `TooltipIconButton` and `ComposerTriggerPopover`. They take their data as props. The [react reference](https://superassist.app/reference/react.md#the-panels-pieces) lists them.

---

# Swap a card

> Replace one of the package's cards, the confirm, choices, links, table, spec, comparison or sources card, with a component of your own through cards on AssistedProvider.

A card is how a tool's call shows in the conversation. The package brings seven, and `cards` on `AssistedProvider` replaces any of them for the whole app. A card you leave out stays the package's.

## Replace a card

Write a component that takes the tool call's props, and pass it under the card's key. Define it at module scope, so it keeps its identity across renders:

```tsx
import { type AssistedCards, AssistedProvider } from "@super-assist/react";
import { Fragment } from "react";

const Spec: NonNullable<AssistedCards["spec"]> = ({ args, result }) => {
  if (typeof result !== "string") return null;
  return (
    <dl className="my-2 grid grid-cols-2 gap-1 rounded border p-2 text-sm">
      {args.rows.map(({ label, value }) => (
        <Fragment key={label}>
          <dt className="text-muted-foreground">{label}</dt>
          <dd>{value}</dd>
        </Fragment>
      ))}
    </dl>
  );
};

const cards: AssistedCards = { spec: Spec };

<AssistedProvider runtime={runtime} cards={cards}>
  {children}
</AssistedProvider>;
```

`args` holds the model's arguments, typed per card. `result` is the call's answer once it has one. The package's show cards wait for it, so a call the browser has not run yet shows nothing.

## Answer a waiting call

The confirm and choices cards pause the call until the user answers. Their components get `interrupt`, set while the call waits, and `resume`, which answers it:

```tsx
const Confirm: NonNullable<AssistedCards["confirm"]> = ({ interrupt, resume, result }) => {
  const ask = interrupt?.payload as { label: string } | undefined;
  if (!ask) return result === undefined ? null : <p className="text-xs">Answered.</p>;
  return (
    <div className="my-2 flex items-center gap-2 rounded border p-2 text-sm">
      <span className="flex-1">{ask.label}</span>
      <button onClick={() => resume({ approved: false })}>Deny</button>
      <button onClick={() => resume({ approved: true })}>Approve</button>
    </div>
  );
};
```

| Key       | `interrupt.payload`     | Answer with                                                   |
| --------- | ----------------------- | ------------------------------------------------------------- |
| `confirm` | `{ name, label, id? }`  | `resume({ approved: true })` or `resume({ approved: false })` |
| `choices` | `{ question, options }` | `resume(option)`, one of the options                          |

The `confirm` card serves every consequential action and tool. A tool's own `render` on `useAssistedTool` replaces it for that tool only.

## The keys

| Key          | Tool                                | `args`                                     |
| ------------ | ----------------------------------- | ------------------------------------------ |
| `confirm`    | Every consequential action and tool | The action's or tool's arguments           |
| `choices`    | `offer_choices`                     | `{ question, options }`                    |
| `links`      | `show_links`                        | `{ items: { to, id?, title, gist? }[] }`   |
| `table`      | `show_table`                        | `{ title?, columns, rows }`                |
| `spec`       | `show_spec`                         | `{ title, rows }`                          |
| `comparison` | `show_comparison`                   | `{ traits, options, recommended, reason }` |
| `sources`    | `search_knowledge`, on the server   | `{ query, knowledgeBase? }`                |

What each tool sends and answers is on its card's page under [Cards](https://superassist.app/components.md#cards). The model still calls the same tools: a card changes how a call looks, never what the model sees.

---

# Show a table, a spec or a comparison

> Have the assistant answer with a table, a spec sheet or a side-by-side comparison through the show tools, and steer when it uses them.

The show tools let the assistant answer with structure instead of prose. `AssistedProvider` lends all three on every page, so there is nothing to install. This page is about getting the answers you want from them.

| Tool              | Shows                                                       | Card                                                  |
| ----------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
| `show_table`      | Records of one kind as rows, their shared fields as columns | [Table card](https://superassist.app/components/cards/table-card.md)           |
| `show_spec`       | One thing's properties as label and value rows              | [Spec card](https://superassist.app/components/cards/spec-card.md)             |
| `show_comparison` | Two or three options side by side, with a recommendation    | [Comparison card](https://superassist.app/components/cards/comparison-card.md) |

A show tool changes nothing on the page. Its call answers `Showed the user a table.`, `a spec sheet.` or `a comparison.`, and the card renders the model's arguments.

## Know when the model reaches for them

The universal instructions tell the model when, in this line:

```txt wrap
Answer with a card when it saves the user typing or reading: show_links when several pages are worth opening, like what to look at next; offer_choices when your question has two to four short answers; and when the user asks to see data laid out, show_table for records of one kind, show_spec for one thing's properties, show_comparison for two or three options side by side. End the turn with at least one sentence, after a card too.
```

So the model shows a card when the user asks to see data laid out, and writes a sentence after it. In the example shop:

| The user asks, on                           | The assistant calls                        |
| ------------------------------------------- | ------------------------------------------ |
| Orders: "List the open orders as a table"   | `get_page_content`, then `show_table`      |
| Settings: "Show the settings as a sheet"    | `get_page_content`, then `show_spec`       |
| Orders: "Compare orders #1042 and #1043"    | `get_page_content`, then `show_comparison` |
| Dashboard: "What needs my attention today?" | `get_page_content`, then `show_table`      |

## Give it the data

The model fills a card from what it has read, so the page has to lend the values. Return them from `content`, with the fields a user would scan:

```tsx
<AssistedPage
  name="Orders"
  instructions="Every order of the shop. Ship an order that is waiting to ship by its id."
  content={() => orders.map(({ id, customer, total, status }) => ({ id, customer, total, status }))}
>
```

The model calls `get_page_content` first and copies ids and values from its answer, as the universal instructions require.

## Steer it from the page

A page's `instructions` win over the universal ones. Say which card fits the page, or that it should answer in prose:

```tsx
<AssistedPage
  name="Orders"
  instructions="Every order of the shop. When the user asks about several orders, show them with show_table: customer, total and status."
  content={() => orders}
>
```

## Change how they look

The cards are the package's. To render a call your own way, pass `cards.table`, `cards.spec` or `cards.comparison` to `AssistedProvider`. See [Swap a card](https://superassist.app/how-to/swap-a-card.md).

The tools' parameters are listed on each card's page and in [Model context](https://superassist.app/reference/model-context.md#built-in-tools).

---

# Mount the devtools

> Add the devtools with the Assisted pages tab to see what each page lends, from the panel's header or as a launcher.

The **Assisted pages** tab shows what the open page lends the assistant. It lives in the devtools entry, `@super-assist/react/devtools`.

## Install the devtools

```bash
npm install @assistant-ui/react-devtools
```

It is an optional peer of `@super-assist/react`. Only the `@super-assist/react/devtools` entry imports it, so an app without it never loads it.

## Open them from the panel

Pass `AssistedDevtoolsPanel` as the panel's `devtools`. The header gets a Bug button that opens the devtools in a window of their own, with the Assisted pages tab:

```tsx
import { AssistedDevtoolsPanel } from "@super-assist/react/devtools";

<AssistedPanel mode="floating" devtools={<AssistedDevtoolsPanel />} />;
```

In a header you compose, place `AssistedPanel.Devtools` with the devtools as its children:

```tsx
<AssistedPanel.Header>
  <AssistedPanel.Title />
  <AssistedPanel.Devtools>
    <AssistedDevtoolsPanel />
  </AssistedPanel.Devtools>
  <AssistedPanel.Close />
</AssistedPanel.Header>
```

`AssistedDevtoolsPanel` works in production builds too: while it is open it registers the runtime with the devtools, which assistant-ui does only in development. Pass it only to the people who should see it, for example `devtools={import.meta.env.DEV && <AssistedDevtoolsPanel />}` in Vite for development alone.

## Or render the launcher

An embedded panel has no header by default. Render `AssistedDevtools` inside `AssistedProvider` instead. From `examples/app/app/assistant.tsx`:

```tsx
<div className="w-md shrink-0 border-s">
  {panel}
  <AssistedDevtools />
</div>
```

`AssistedDevtools` is the devtools' `DevToolsModal` with the tab added. If you already render your own `DevToolsModal`, add the plugin to it instead:

```tsx
const plugins = [assistedPagesPlugin];

export function Devtools() {
  return <DevToolsModal plugins={plugins} />;
}
```

## Open the tab

Press the panel's Bug button, or, with `AssistedDevtools` in a development build, the launcher in the bottom-right corner. Pick **Assisted pages**. It re-reads every second and follows client navigation.

`DevToolsModal` renders nothing in production builds. The tab's module still ships with the app.

The tab's sections are listed in the [devtools reference](https://superassist.app/reference/devtools.md).

---

# @super-assist/react

> The package's entries and peers, useAssistedRuntime, and every export with the page that documents it.

## Package

| Field          | Value                                                                                   |
| -------------- | --------------------------------------------------------------------------------------- |
| Install        | `npm install @super-assist/react`                                                       |
| Entries        | `@super-assist/react`, `@super-assist/react/devtools`, `@super-assist/react/styles.css` |
| Peers          | `react` ^19.3.0, `react-dom` ^19.3.0                                                    |
| Optional peers | `@assistant-ui/react-devtools` ^1.2.23, for the `/devtools` entry.                      |

The runtime's own packages, `agents`, `@cloudflare/ai-chat` and `ai`, are dependencies and install with it.

## Entries

| Entry                            | What it holds                                                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `@super-assist/react`            | `useAssistedRuntime`, the provider, the page, actions, fields and tools, the panel and its parts, the hooks and primitives. |
| `@super-assist/react/devtools`   | The devtools tab. See the [devtools reference](https://superassist.app/reference/devtools.md).                                                       |
| `@super-assist/react/styles.css` | The panel's compiled styles. See the [styles reference](https://superassist.app/reference/styles.md).                                                |

## useAssistedRuntime

```ts
useAssistedRuntime(options: UseAssistedRuntimeOptions): AssistantRuntime
```

Connects the panel to a Super Assist project, or to a route of the host's own, and returns the runtime to pass to `AssistedProvider`. Pass a `key` or a `basePath`, not both.

| Option              | Type                                    | Description                                                                                                    |
| ------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `key`               | `string`                                | The project's publishable key, `pk_` and 32 characters.                                                        |
| `agent`             | `string`                                | With a key: an agent's id, to answer with it instead of the project's default agent.                           |
| `user`              | `{ id: string; name?; email? }`         | With a key: the signed-in user, taken as unverified. Without one, the browser is a visitor.                    |
| `basePath`          | `string`                                | A route the host authenticates itself, with the Directory under it and each thread under `basePath/:id`.       |
| `host`              | `string`                                | The origin the sockets open on. `https://superassist.app` with a key, the page's own origin with a `basePath`. |
| `thread`            | `string`                                | The thread to open. The hook opens it when it changes.                                                         |
| `onThreadChange`    | `(id: string) => void`                  | Called with the open thread's id whenever it changes, including the hook's first pick.                         |
| `onConnectionError` | `(error: AgentConnectionError) => void` | Called when the connection is refused. `console.error` by default.                                             |

- Every message carries `system`, `config` and `callSettings`, read from the model context when it is sent. A continuation after a tool result reuses them from the user's last message.
- The lent tools go as `clientTools` with every message and tool result, kept in step with the model context.
- A visitor's id is kept in `localStorage` under `super-assist:visitor:<key>`. Where storage is unavailable, the hook makes a new one.
- The runtime's thread list is the end user's threads, most recently active first. The hook opens `thread`, else the first, and starts a thread when there are none. New thread, rename and delete go to Super Assist.
- Each thread gets its own message store, so switching threads never shows the previous thread's messages under the new one.
- A refused connection closes with `4401`, `4403`, `4404` or `4400` and is not retried. See [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md#handle-a-refused-connection).

Type: `UseAssistedRuntimeOptions`.

## Exports of the main entry

### What a page lends

Each export's props and behavior are on its page under Components.

- [`AssistedProvider`](https://superassist.app/components/package/assisted-provider.md#props): wraps the app in the runtime and lends what every page shares.
- [`useAssisted`](https://superassist.app/components/package/assisted-provider.md#useassisted): reads and drives the panel's open state and the open page's name.
- [`AssistedPage`](https://superassist.app/components/package/assisted-page.md#props): introduces a page, or a dialog over it.
- [`AssistedAction`](https://superassist.app/components/package/assisted-action.md#props) and [`useAssistedAction`](https://superassist.app/components/package/assisted-action.md#useassistedaction): an element the assistant presses, rings or asks about.
- [`AssistedInput`](https://superassist.app/components/package/assisted-input.md#props) and [`useAssistedInput`](https://superassist.app/components/package/assisted-input.md#useassistedinput): a native field the assistant fills.
- [`AssistedField`](https://superassist.app/components/package/assisted-field.md#props): a control that keeps its value in state.
- [`useAssistedTool`](https://superassist.app/components/package/use-assisted-tool.md#signature): a tool that runs in the browser.
- [`ring`](https://superassist.app/components/package/assisted-action.md#ring) and [`useRing`](https://superassist.app/components/package/assisted-action.md#usering): point at one element.
- [`AssistedCards`](https://superassist.app/components/package/assisted-provider.md#assistedcards): the type of the provider's `cards`.

### AssistedPanel

`AssistedPanel` is the one-liner, and its members are the parts. Each group's parts, props and default composition are on its page.

| Group                                                   | Members                                                                                                                                                                    |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Roots and window](https://superassist.app/components/panel/roots-and-window.md) | `Floating`, `Sheet`, `Embedded`, `Main`, `Launcher`, `Trigger`, `WindowControls`                                                                                           |
| [Header](https://superassist.app/components/panel/header.md)                     | `Header`, `Footer`, `Icon`, `Title`, `PageLine`, `Close`, `Devtools`                                                                                                       |
| [Threads](https://superassist.app/components/panel/threads.md)                   | `Threads`, `ThreadMenu`, `ThreadSelect`, `ThreadDrawerToggle`, `ThreadDrawer`, `ThreadTitle`, `NewThread`, `DeleteThread`                                                  |
| [Conversation](https://superassist.app/components/panel/conversation.md)         | `Conversation`, `HistorySkeleton`, `EmptyState`, `Messages`, `FollowUps`, `HandoffOffer`, `Resolution`, `ScrollToBottom`, `ConversationSearch`, `ConversationSearchToggle` |
| [Composer](https://superassist.app/components/panel/composer.md)                 | `Composer`, `Attachments`, `Input`, `AddAttachment`, `Dictate`, `ModelSelector`, `Send`                                                                                    |
| [Data parts](https://superassist.app/components/panel/data-parts.md)             | `SettingsToggle`, `SettingsPanel`, `ContextDisplay`, `ContextBreakdown`, `QuotaBanner`                                                                                     |

Types: `AssistedPanelProps`, `AssistedPanelFloatingProps`, `AssistedPanelSheetProps`, `AssistedPanelEmbeddedProps`, `AssistedPanelOptions`, `AssistedPanelWindowProps`, `ThreadComponents`.

### Runtime, hooks and primitives

| Export                                                                                                                                                                                                                      | Kind       | Description                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `useAui`                                                                                                                                                                                                                    | Hook       | The client that acts on the runtime: `aui.threads`, `aui.thread`, `aui.composer`.                          |
| `useAuiState`                                                                                                                                                                                                               | Hook       | Selects from the runtime's state, `s.thread` and `s.threads`, and re-renders on change.                    |
| `useAuiEvent`                                                                                                                                                                                                               | Hook       | Subscribes to one of the runtime's events.                                                                 |
| `AuiIf`                                                                                                                                                                                                                     | Component  | Renders its children while a condition on the state holds.                                                 |
| `AssistantRuntimeProvider`, `AuiProvider`                                                                                                                                                                                   | Component  | Provide a runtime, and a client over it. `AssistedProvider` renders the first for you.                     |
| `tool`, `makeAssistantTool`                                                                                                                                                                                                 | Function   | Define a tool outside `useAssistedTool`.                                                                   |
| `ThreadPrimitive`, `MessagePrimitive`, `ComposerPrimitive`, `ActionBarPrimitive`, `BranchPickerPrimitive`, `AttachmentPrimitive`, `ErrorPrimitive`, `SuggestionPrimitive`, `ThreadListPrimitive`, `ThreadListItemPrimitive` | Components | Unstyled building blocks with the panel's behavior. See [Make your own part](https://superassist.app/how-to/make-your-own-part.md). |

Type: `AssistantRuntime`.

### The panel's pieces

The components the parts are built from. They take their data as props, for parts of your own that keep the panel's look.

| Export                                                                              | What it is                                                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ThreadList`                                                                        | The runtime's threads with a New Thread button, as `Threads` and the drawer show them.                 |
| `ModelSelector`, type `ModelOption`                                                 | The model picker, controlled by `models`, `value` and `onValueChange`.                                 |
| `EmptyState`, `EmptyStateGreeting`, `EmptyStateSuggestions`, `EmptyStateSuggestion` | The empty state's layout.                                                                              |
| `ConversationSearch`, type `SearchHit`                                              | The search box over a conversation.                                                                    |
| `ThreadSearch`, type `SearchableThread`                                             | The searchable thread list in the menu.                                                                |
| `StoppedRun`                                                                        | The stopped reply's card.                                                                              |
| `ApprovalCard`, type `ApprovalState`                                                | The confirm card's look.                                                                               |
| `OptionList`, type `OptionListOption`                                               | The choices card's look.                                                                               |
| `DataTable`, types `DataTableColumn`, `DataTableRow`                                | The table card's look.                                                                                 |
| `SpecSheet`, type `SpecRow`                                                         | The spec card's look.                                                                                  |
| `ComparisonCard`, type `ComparisonOption`                                           | The comparison card's look.                                                                            |
| `Sources`, type `SourcePassage`                                                     | The sources card's look.                                                                               |
| `SettingsPanel`, type `SettingToggle`                                               | The settings' look.                                                                                    |
| `ContextBreakdown`, type `ContextSegment`                                           | The breakdown's look.                                                                                  |
| `QuotaBanner`                                                                       | The quota banner.                                                                                      |
| `LauncherBubble`, `Suggestions`, `TooltipIconButton`, `ComposerTriggerPopover`      | A launcher bubble, a row of suggestions, an icon button with a tooltip, and the slash-command popover. |

The parts under `AssistedPanel` read the panel's state. These do not: pass them their data.

Types of the rest: `AssistedProviderProps`, `AssistedPageProps`, `AssistedActionProps`, `AssistedActionOptions`, `AssistedInputProps`, `AssistedInputOptions`, `AssistedFieldProps`, `AssistedFieldOption`, `AssistedTool`, `AssistedToolFailure`, `RingOptions`, each described with its component or hook.

---

# @super-assist/react/styles.css

> The panel's compiled stylesheet, its scoped reset, its class prefix, and the --super-assist-* tokens with their shadcn fallbacks.

## Entry

| Field   | Value                                                                      |
| ------- | -------------------------------------------------------------------------- |
| Import  | `import "@super-assist/react/styles.css";`, once, anywhere in the app      |
| Format  | Plain compiled CSS. The host needs no Tailwind and no build step for it.   |
| Layers  | `theme`, `base`, `components`, `utilities`                                 |
| Classes | Prefixed `sa:`, so they never meet the host's own utility classes.         |
| Dark    | The panel's dark styles apply under a `.dark` ancestor, as shadcn sets it. |

## Scope

Every panel root, the launcher, the trigger and the floating windows carry `data-super-assist`. The stylesheet's reset applies under that attribute only, inside `:where()`, so any selector of the host's beats it.

| Under `[data-super-assist]` | Reset                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| The root                    | `font-family` from `--super-assist-font-sans`, `line-height: 1.5`, the foreground color, antialiasing. |
| Every element               | `box-sizing: border-box`, no margin, no padding, a 0 border in the border color.                       |
| Headings                    | The surrounding size and weight.                                                                       |
| Lists                       | No markers.                                                                                            |
| Media                       | `display: block`. Images and videos at most full width.                                                |
| Form controls and buttons   | The surrounding font and color, a transparent background, no radius.                                   |
| Links                       | The surrounding color, no underline.                                                                   |

The host page outside the panel is untouched.

## Tokens

Each color and the radius read a `--super-assist-*` variable first, then shadcn's variable of the same name, then a zinc default. A shadcn app gets its own theme with nothing set. Set a `--super-assist-*` variable to give the panel a value of its own:

```css
:root {
  --super-assist-primary: oklch(0.55 0.15 160);
  --super-assist-radius: 0.5rem;
}
```

| Token                                 | Falls back to            | Default                                                    |
| ------------------------------------- | ------------------------ | ---------------------------------------------------------- |
| `--super-assist-background`           | `--background`           | `oklch(1 0 0)`                                             |
| `--super-assist-foreground`           | `--foreground`           | `oklch(0.141 0.005 285.823)`                               |
| `--super-assist-card`                 | `--card`                 | `oklch(1 0 0)`                                             |
| `--super-assist-card-foreground`      | `--card-foreground`      | `oklch(0.141 0.005 285.823)`                               |
| `--super-assist-popover`              | `--popover`              | `oklch(1 0 0)`                                             |
| `--super-assist-popover-foreground`   | `--popover-foreground`   | `oklch(0.141 0.005 285.823)`                               |
| `--super-assist-primary`              | `--primary`              | `oklch(0.21 0.006 285.885)`                                |
| `--super-assist-primary-foreground`   | `--primary-foreground`   | `oklch(0.985 0 0)`                                         |
| `--super-assist-secondary`            | `--secondary`            | `oklch(0.967 0.001 286.375)`                               |
| `--super-assist-secondary-foreground` | `--secondary-foreground` | `oklch(0.21 0.006 285.885)`                                |
| `--super-assist-muted`                | `--muted`                | `oklch(0.967 0.001 286.375)`                               |
| `--super-assist-muted-foreground`     | `--muted-foreground`     | `oklch(0.552 0.016 285.938)`                               |
| `--super-assist-accent`               | `--accent`               | `oklch(0.967 0.001 286.375)`                               |
| `--super-assist-accent-foreground`    | `--accent-foreground`    | `oklch(0.21 0.006 285.885)`                                |
| `--super-assist-destructive`          | `--destructive`          | `oklch(0.577 0.245 27.325)`                                |
| `--super-assist-border`               | `--border`               | `oklch(0.92 0.004 286.32)`                                 |
| `--super-assist-input`                | `--input`                | `oklch(0.92 0.004 286.32)`                                 |
| `--super-assist-ring`                 | `--ring`                 | `oklch(0.705 0.015 286.067)`                               |
| `--super-assist-radius`               | `--radius`               | `0.625rem`                                                 |
| `--super-assist-font-sans`            | `--font-sans`            | `ui-sans-serif, system-ui, sans-serif` and the emoji fonts |

The radius scale derives from `--super-assist-radius`: small is 4 px less, medium 2 px less, large equal, extra large 4 px more, 2xl 8 px more.

The defaults are light. In a dark theme without shadcn's variables, set the `--super-assist-*` colors under `.dark`.

---

# @super-assist/react/devtools

> The devtools entry and its Assisted pages tab.

## Entry

| Field    | Value                                                                     |
| -------- | ------------------------------------------------------------------------- |
| Import   | `@super-assist/react/devtools`                                            |
| Requires | `@assistant-ui/react-devtools`, an optional peer of `@super-assist/react` |

## Exports

| Export                  | Kind            | Description                                                                                                                                                                                                        |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AssistedDevtools`      | Component       | The devtools' `DevToolsModal` with `assistedPagesPlugin` as its plugin. No props.                                                                                                                                  |
| `AssistedDevtoolsPanel` | Component       | The devtools' `DevToolsPanel` with the same plugin, in its own shadow root, filling its container. `theme`, `"light"` or `"dark"`, defaults to `"light"`. For the panel's `devtools` and `AssistedPanel.Devtools`. |
| `assistedPagesPlugin`   | Devtools plugin | The tab, made with `createDevToolsPlugin`. Id `assisted-pages`, label "Assisted pages".                                                                                                                            |

- Render either inside `AssistedProvider`. Outside it, the tab reads "No AssistedProvider here.".
- `DevToolsModal` renders nothing in production builds. `AssistedDevtoolsPanel` works in every build, registering the runtime with the devtools while it is mounted, so pass it only to the people who should see it.

## The tab

The tab re-reads every second while it is mounted.

| Section                      | Shows                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| Page                         | The open assisted page's name, or "No assisted page is open.".                        |
| Note the next turn sends     | The open page's note.                                                                 |
| get_page_content answers now | What `get_page_content` answers, called each second, or "The page lends no content.". |
| Actions                      | The open page's actions.                                                              |
| Fields                       | The open page's field tools, each with what every field says now.                     |
| Page tools                   | The open page's tools.                                                                |
| Global tools                 | Every other lent tool, the built-ins included.                                        |
| Destinations                 | Each destination's name and path, when the provider has `destinations`.               |

Each listed tool shows its name, a `ring` or `confirm` chip read from its markers, `id: <ids>` for a grouped action or field, and its description. A field tool also shows `<id> now <value>` for each field, or `now <value>` for a field without an id. Tools that have left are not listed.

---

# Model context

> The system text, tools and answers the library lends the assistant through the model context, and the cards its tools render.

Everything here reaches the backend in each request's `system` and `tools`.

## Universal instructions

Lent by `AssistedProvider` on every page:

```md
## Working beside the page

You sit beside the page the user has open in this app. The page section, headed "The page the user has open", gives that page's name, its instructions for working there, and the tools and actions it lends you. It describes the page as of the user's latest message, so it is newer than every tool result before that message. A tool result after that message that describes the page is newer still and holds for the rest of your turn. With no page section, the page hasn't introduced itself: work from the conversation.

The page section holds no content. For anything about what the user is looking at, call get_page_content first when the page lends it, and take every id and value from its answer.

The page's tools act on what the user has open, so make the change with them yourself. The page's fields are tools of their names that fill them, and the page section shows what each says now. A page's tools and actions leave with it; a call to one that has left answers with the page the user is on now.

The page's actions are things on it you press by calling them, as the user would click them, and each answers with the page as the press left it. An action marked consequential is the user's to press, so when it is what they asked for, call it: the call only rings it, pointing it out on the page, then tell the user it is ready for them. An action or tool marked asks first is yours to call: the panel asks the user, it goes ahead only on their approval, and their decline is final.

When the user asks to go somewhere in the app, or the work is on another page, open it with go_to_page.

Answer with a card when it saves the user typing or reading: show_links when several pages are worth opening, like what to look at next; offer_choices when your question has two to four short answers; and when the user asks to see data laid out, show_table for records of one kind, show_spec for one thing's properties, show_comparison for two or three options side by side. End the turn with at least one sentence, after a card too.

When a tool answers with an error, say what you tried and what it answered, then offer the next step. Call it again only with something changed.

Where the app's own instructions differ from these, follow the app's.
```

## The page note

Lent by the open `AssistedPage` and read at send time. Empty parts drop. Names are sorted.

```md
## The page the user has open: <name>

<instructions>

Its tools: <page tools>.

Its actions: <actions>.

Its fields: <fields>.
```

Each field reads `<name>: <label>, now <value>`. Same-name fields read `<name> (<id>: <label>, now <value>; …)`. Fields are separated by commas. `<value>` is shown as the [`AssistedInput` page](https://superassist.app/components/package/assisted-input.md#props) lists it, and as `not showing` while the element is missing.

The example's Settings page:

```md
## The page the user has open: Settings

The shop's name, currency and notification email. setting fills one field by its id without saving; Save saves the form.

Its tools: get_page_content.

Its actions: save_settings.

Its fields: setting (name: Shop name, now "Northwind"; currency: Currency, now "USD"; email: Notification email, now "alerts@northwind.example").
```

The example's Orders page, with orders waiting to ship:

```md
## The page the user has open: Orders

Every order of the shop, as filtered by status with filter_orders, and charted by status with chart_orders. Ship or cancel an order that is waiting to ship by its id. New order opens a dialog that introduces itself. Each order has a page of its own with its note and refund.

Its tools: filter_orders, chart_orders, get_page_content.

Its actions: cancel_order, new_order, ship_order.
```

## Markers

| Marker             | Appended to                                                                                                    | Meaning                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| ` (consequential)` | An action's label with `consequential`, or a field's label with `consequential` or an element of no known kind | Calling it rings it.           |
| ` (asks first)`    | An action's label with `consequential="confirm"`, or a tool's description with `consequential: true`           | The panel asks before it runs. |

## Built-in tools

| Tool               | Lent when                               | Parameters                                                                                        |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `get_page_content` | The open page has `content`             | None                                                                                              |
| `go_to_page`       | `destinations` and `navigate` are given | `to`: a destination name. `id`: fills `:id`.                                                      |
| `show_links`       | `destinations` and `navigate` are given | `items`: one or more of `{ to, id?, title, gist? }`                                               |
| `offer_choices`    | Always                                  | `question`: a string. `options`: two to four strings.                                             |
| `show_table`       | Always                                  | `title?`, `columns`: one or more `{ key, label }`. `rows`: values by column key.                  |
| `show_spec`        | Always                                  | `title`, `rows`: one or more `{ label, value }`.                                                  |
| `show_comparison`  | Always                                  | `traits`: strings. `options`: two or three `{ name, headline, traits }`. `recommended`, `reason`. |

| Tool               | Description                                                                                                                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_page_content` | What the page the user has open shows right now. Call it first for anything about this page.                                                                                                             |
| `go_to_page`       | Open a page of the app for the user and answer, once it has loaded, with the page section of the page it opened. The pages and their paths: `<name> <path>`, …, or `destinationsDescription` when given. |
| `show_links`       | Show the user links to pages of the app, the pages go_to_page opens, each with a title and a one-line gist. A click opens the page.                                                                      |
| `offer_choices`    | Ask the user a question with two to four short answers they pick with one click, and answer with their pick.                                                                                             |
| `show_table`       | Show the user a table: records of the same kind as rows, the fields they share as columns. For structured answers the user can scan, like a list of orders.                                              |
| `show_spec`        | Show the user a spec sheet: one thing's properties as label and value rows. For structured answers the user can scan, like an order's details or a page's settings.                                      |
| `show_comparison`  | Show the user two or three options side by side on the same traits, with the one you recommend and why. For structured answers the user can scan, like comparing two orders.                             |

| Tool                                         | Answers                                                                              |
| -------------------------------------------- | ------------------------------------------------------------------------------------ |
| `get_page_content`                           | The page's `content`.                                                                |
| `go_to_page`                                 | `Opened <path>.` and the note of the page open after the change, or after 5 seconds. |
| `go_to_page`, `show_links`                   | `{ error: 'No page "<to>". The pages are <names>.' }` for an unknown name.           |
| `go_to_page`, `show_links`                   | `{ error: "The <to> page needs an id." }` when the path has `:id` and no id came.    |
| `show_links`                                 | `Showed the user links to <titles>.`                                                 |
| `offer_choices`                              | `The user picked "<option>".`, once the user picks.                                  |
| `show_table`, `show_spec`, `show_comparison` | `Showed the user a table.`, `a spec sheet.` or `a comparison.`                       |

## Action answers

| Case        | Answer                                                                               |
| ----------- | ------------------------------------------------------------------------------------ |
| Pressed     | `Pressed "<label>".` and the page's note after the press.                            |
| Rung        | `Rang "<label>" for the user; pressing it is theirs.`                                |
| Approved    | `Approved by the user and pressed "<label>".` and the page's note after the press.   |
| Declined    | `The user declined "<label>". That is final: leave it unless they ask for it again.` |
| Not mounted | `{ error: '"<label>" isn't showing.' }`                                              |
| Disabled    | `{ error: '"<label>" is disabled right now.' }`                                      |
| Unknown id  | `{ error: 'No <name> has the id "<id>". Its ids are <ids>.' }`                       |

## Field tools

| Shape               | Description                                      | Parameters                                                              |
| ------------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| One field of a name | `Fill the field: <entry>.`                       | `{ value }`, required                                                   |
| Same-name fields    | `Fill one of these by its id. <id>: <entry>; ….` | `{ id, value }`, both required, `id` an enum of the mounted fields' ids |

`<entry>` is the label, then its marker, then `, one of <options>` when the field has options. Each option is its value as a JSON string, followed by ` (<label>)` when it has a label.

`value` is `{ type: "string", description: "What the field should say." }`. It gains an `enum` of the options when every field of the tool has options.

## Field answers

| Case            | Answer                                                                      |
| --------------- | --------------------------------------------------------------------------- |
| Filled          | `Filled "<label>"; it now says <value>.`, once React has committed the fill |
| Rung            | `Rang "<label>" for the user; filling it is theirs.`                        |
| Not mounted     | `{ error: '"<label>" isn't showing.' }`                                     |
| Disabled        | `{ error: '"<label>" is disabled right now.' }`                             |
| Read-only       | `{ error: '"<label>" is read-only right now.' }`                            |
| Unknown id      | `{ error: 'No <name> has the id "<id>". Its ids are <ids>.' }`              |
| `onFill` throws | `{ error: "<name> failed: <message>" }`                                     |

A fill answers without the page's note. The note sent with the next message shows every field's value.

## Tool answers

| Case                    | Answer                                                                            |
| ----------------------- | --------------------------------------------------------------------------------- |
| `execute` returns       | Its value.                                                                        |
| `execute` throws        | `{ error: "<name> failed: <message>" }`                                           |
| Arguments rejected      | `{ error: "<name> got arguments its parameters reject: <issues>" }`               |
| Declined                | `The user declined <name>. That is final: leave it unless they ask for it again.` |
| Tool or action has left | `{ error }` holding `The page no longer offers <name>.` and the open page's note. |

A tool or action that has left stays in model context as a disabled tool. The runtime leaves it out of the schemas sent to the backend, and still runs it when the model calls it from an earlier request.

## Confirm pause

Consequential calls with `"confirm"`, and consequential tools, pause through `human()` in the tool's execution context.

| Part    | Shape                                                                                   |
| ------- | --------------------------------------------------------------------------------------- |
| Payload | `{ name: string; label: string; id?: string }`. For a tool, `label` is its description. |
| Resume  | `{ approved: boolean }`. Only `approved: true` goes ahead.                              |

## Cards

Every card renders inline in the conversation, outside the group that folds consecutive tool calls. `cards` on `AssistedProvider` replaces any of them. Each has a page under [Cards](https://superassist.app/components.md#cards).

| Card       | Renders for                     | Shown                                         | Marker                         |
| ---------- | ------------------------------- | --------------------------------------------- | ------------------------------ |
| Confirm    | Consequential actions and tools | While the call waits, then as a receipt       | `data-slot="approval-card"`    |
| Choices    | `offer_choices`                 | While the call waits, then with only the pick | `data-slot="assisted-choices"` |
| Links      | `show_links`                    | Once it answers without an error              | `data-slot="assisted-links"`   |
| Table      | `show_table`                    | Once it answers                               | `data-slot="assisted-table"`   |
| Spec       | `show_spec`                     | Once it answers                               | `data-slot="spec-sheet"`       |
| Comparison | `show_comparison`               | Once it answers                               | `data-slot="comparison-card"`  |

The confirm card's receipt reads "Approved, running", "Finished", "Denied", or "Didn't go through" when the press fails. Each link of the links card is an `a` with the page's path as its `href`.

---

# How a turn is answered

> What happens between a message in the panel and its reply, from the project and its agent to the agent's skills and databases and what the page lends.

The panel runs in your app's pages, and Super Assist answers. Every turn draws on two sources: what your organization set up in the dashboard, and what the open page lends at that moment. This page follows one message from the panel to the reply.

## The project lets the panel in

The panel connects with the project's publishable key. Before anything else runs, Super Assist checks four things:

- The key belongs to a project.
- The page's origin is one of the project's allowed origins.
- The agent belongs to the organization. It is the project's default agent, or the one the hook's `agent` option names.
- The panel names an end user: the signed-in user you pass, or a visitor id the browser keeps.

A failed check closes the connection with a code, and nothing else happens. The codes are in [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md#handle-a-refused-connection).

The key grants nothing past this door. It opens threads for its project from the allowed origins. It can't change an agent, read a database or pick a model, so it is safe to ship in your bundle.

## Each end user has their own threads

An end user gets their own list of threads with each agent in each project, and sees only those. A visitor's list stays with their browser, and a signed-in user's follows them across browsers. The first message names a thread, and each turn moves its thread to the top.

The agent keeps notes as it works. Each thread has its own memory for that conversation. The end user's threads with the agent also share one memory, for facts that should outlast a conversation. No other end user sees either.

## The agent answers

The agent is what your organization configured in the dashboard:

- **Instructions.** A template filled in at every turn with the date, the agent, the organization, and the agent's skills and databases. Instructions saved while a conversation runs apply from its next turn.
- **A model.** An end user's turn always runs on the agent's model and thinking level. The panel's model choice is ignored, so a browser holding the key can't run another model on your organization's spend.
- **Skills.** The prompt lists each of the agent's skills by name and description. The agent loads a skill's instructions only when the description fits the request. So the skill editor writes the description as three labelled lines from its **What**, **Use when**, and **Not for** fields:

  ```text
  What: Reviews a pull request against the team checklist.
  Use when: Asked to review a pull request, a diff or a branch.
  Not for: Writing the fix or reviewing a design doc.
  ```

  **Not for** keeps the agent from loading a skill for a request that only looks like a fit. Through the API, write the same lines into `description`. A description written another way opens in the editor whole, under **What**.

- **Databases.** An agent with databases gets two tools: one returns a database's schema, and one runs a single SQLite statement. A statement that writes to a database the agent may only read is rolled back.
- **Knowledge bases.** An agent with knowledge bases gets `search_knowledge`, and its prompt tells it to search before answering a question they may cover, to answer from the passages, and to cite no source the search didn't return. The passages show under the answer in the [sources card](https://superassist.app/components/cards/sources-card.md). See [Knowledge bases](https://superassist.app/dashboard/knowledge-bases.md).
- **The core rules.** Four fixed rules close every prompt, whatever the instructions say: answer only from the instructions, the knowledge bases, the open page and tool results; one step at a time; claim an action done only when a tool call completed it; say what a handoff or a consequential page action will do and wait for a yes.

In an end user's thread the agent can't fetch URLs. That stays with your members, who try agents in the dashboard.

## After the reply, a decision model reads the exchange

Once the reply is on screen, one call to Clef, Cloudflare's decision model, reads the agent's purpose and the last thirty turns and answers six questions at once: is the issue resolved, is the user done, should a person take over and why, did the reply stray off the agent's purpose, and did it expose something it shouldn't. The answers are the thread's signal, and the next user message clears it.

- **The resolution prompt.** The panel asks **Did this resolve your issue?** under the reply only when the issue reads as resolved or the user reads as done, not after every reply. The answer sets the thread's outcome on the project's page.
- **The handoff offer.** When a person reads as needed, the panel shows **Talk to a person**. Pressing it sends "I'd like to talk to a person." and the agent hands off. A user who plainly asked for a person is handed off at once, without another turn.
- **Flags.** A reply that strayed off purpose or exposed something it shouldn't is flagged **Off purpose** or **Sensitive** beside the thread's outcome on the project's page and on the thread.

A reply Clef can't judge is logged and shown as it is; the prompt, the offer and the flags simply stay off for that exchange.

## A person can take over

Every thread has a `handoff` tool. When the agent calls it, or when the signal above says the user asked for a person, a handoff opens, your organization's support address gets an email, and the panel tells the end user a person will reply there. The agent then stays out of the thread: the end user's messages are kept, and no turn runs. A member reads the thread from the dashboard's **Inbox** and replies into it, and the reply reaches the panel as that person's message. Closing the handoff gives the thread back to the agent. See [Handoffs](https://superassist.app/dashboard/handoffs.md).

## The page adds what it lends

Every message from the panel carries what the open page lends through [model context](https://superassist.app/explanation/model-context.md):

- **The instructions and the page's note.** They follow the agent's own instructions in the prompt, so the agent knows which page the user has open and how to work there.
- **The lent tools.** The page's actions, fields and tools, and the provider's built-ins such as `go_to_page` and `show_table`, join the agent's own tools for the turn.
- **The call settings.** A temperature or a system prompt set in the panel's settings applies to the turn.

The lent tools have no code on Super Assist. When the agent calls one, the call streams to the browser, the page runs it, and the result goes back. The agent then continues the same turn. A tool with `toModelOutput` sends its result for the thread and, beside it, the text and files the model sees; Super Assist hands the model those parts, or their text alone when the model takes no files.

When a tool opens another page mid-turn, the next step already has the new page's tools. The page section of the prompt still names the old page until the user writes again. The tool that changed the page answers with the new page's note, and the universal instructions tell the agent that a note in a tool result is newer. So the agent can act on the new page in the same turn.

## The browser keeps the rest

A page's content leaves the browser only when the agent asks for it with `get_page_content`. See [Why content is read on demand](https://superassist.app/explanation/content-on-demand.md).

A consequential action's approval pauses its tool call in the browser. Super Assist sees a tool call whose result arrives late, and needs nothing else for the pause. See [Why consequential actions ring](https://superassist.app/explanation/consequential-actions.md).

## The organization pays for the turn

Super Assist pays the provider for each turn. The first dollars of a month come from the AI your plan includes; the rest come off your organization's credits, bought in packs on the billing page. With nothing included and no credits left, turns are refused.

---

# Why content is read on demand

> Why an assisted page's content never enters the prompt unasked, and the assistant reads it through get_page_content.

An assisted page lends two different things. Its note says where the user is: the page's name, its instructions, and the names of its tools and actions. Its content is what the page shows. The note goes with every message. The content is read only when the assistant calls `get_page_content`.

## What the note is for

The note is small and changes only when the user moves. It lets the assistant answer "where am I and what can I do here" without a tool call, and it tells the assistant which tools and actions exist. Sending it every time costs little.

## Why the content stays out

Content is different in three ways.

- **Size.** A table of orders, a form, a customer list. Most messages do not need it. Putting it in every request would spend the model's context on data the turn never uses.
- **Freshness.** The assistant acts on the page in steps. A filter changes the rows, a field is filled, a save fails with an error. Content read at call time reflects the page as the last step left it. Content captured with the user's message would already be stale after the first tool call.
- **Choice.** Content enters the conversation only when the assistant asks for it, and only for the page the user has open. The host decides what `content` returns, so it can leave out what the model should not see.

The universal instructions close the loop. They say the page section holds no content, and that the assistant calls `get_page_content` first and takes every id and value from its answer. Ids the assistant presses with then come from the page, not from memory.

## Why not lend the DOM

Another way to lend a component puts its HTML into the prompt. That is the opposite trade: everything, every time, as markup. An assisted page lends data the host shapes, through the same tool path as its other tools, so it follows the same rules for leaving with the page.

## The cost

Questions about the page take one tool call more. The assistant has to know to make it, which is why the instructions say so plainly. Hosts that want a fact in every message can put it in `instructions`, which is part of the note.

---

# Why consequential actions ring

> Why an action whose effect the user should own is pointed out to the user, or asked about, instead of pressed.

Some actions have effects the user should own: a refund, a saved setting, a cancelled order. The assistant can be wrong about which order, or about whether the user meant it. For these, the library offers two shapes, and neither lets the assistant act alone.

## Ringing: the user presses

A consequential action rings. The assistant points at the element: it is scrolled into view, ringed, and labeled with what pressing does. Then the assistant tells the user it is ready. The user presses it, or does not.

This keeps the effect in the user's hand and in the page's own UI. The user sees the real button, in its real state, next to the data it acts on. Nothing new to trust appears: no summary of what the assistant thinks it is about to do. If the button is disabled or gone, the ring does not happen, and the assistant hears why.

The ring leaves when the user dismisses it or acts. It does not block the page.

## Confirming: the user approves

Some actions are fine to press once the user agrees, but awkward to find on the page. `consequential="confirm"` asks in the panel instead. The card names the action, and the user approves or denies. On approval the library presses the element itself.

The pause is the tool call's `human()`, which lives in the browser. The backend sees an ordinary tool call whose result arrives late. A denial is a plain answer, not an error: "The user declined … That is final: leave it unless they ask for it again." The instructions tell the assistant the decline is final, so it does not ask again in the same breath.

Before pressing, the library checks the element again. The card may have waited while the row left or the button turned disabled.

## Choosing between them

Ring when the user should see the effect in place before it happens, like a refund on the order's own page. Confirm when the conversation already holds enough context and the press itself is the routine part, like cancelling an order the user just named.

Tools have no element to point at, so a consequential tool always confirms.

## Why not let the backend gate it

Server-side approval gates exist, but they ask about a tool call, not about a thing on the page. Ringing needs the page. Confirming needs the row the assistant picked from a grouped action. Both live where the action does, in the browser, and both work with no backend change.

---

# How model context composes

> How the universal instructions, the open page's note, its tools and actions, and global tools add up to one request.

The runtime keeps one registry of what the model should know and can call: the model context. Components add to it while they are mounted and leave when they unmount. Several providers compose: their system texts concatenate and their tool sets merge. super-assist keeps no registry of its own. Everything it lends goes through this one.

## What each piece lends

| Piece                            | Lends                                                                | How                                       |
| -------------------------------- | -------------------------------------------------------------------- | ----------------------------------------- |
| `AssistedProvider`               | The universal instructions                                           | `useAssistantInstructions`                |
| `AssistedProvider`               | `offer_choices`, and `go_to_page` and `show_links` with destinations | One registration per tool                 |
| The open `AssistedPage`          | Its note                                                             | `useAssistantContext`, read at send time  |
| The open `AssistedPage`          | `get_page_content`, when it has content                              | `useAssistedTool` under the page          |
| `AssistedAction`                 | One tool per name on its page                                        | `useAssistedTool`'s path, grouped by name |
| `AssistedInput`, `AssistedField` | One tool per name on its page, and the note's fields line            | `useAssistedTool`'s path, grouped by name |
| `useAssistedTool`                | One tool                                                             | `aui.modelContext.register`               |

At send time the model context is read once. The backend receives the concatenated system text and the merged tools.

## One page is open

Pages can mount inside each other, like a dialog over a list. The page the user has open is the last one mounted, ordered by when each first rendered. Only that page lends its note and `get_page_content`. A dialog that mounts becomes the open page. When it closes, the page under it is open again.

A page under the open one keeps its tools and actions lent, but no note names them. The model can still call them. The note tells it which ones belong to what the user sees.

## Tools belong to where they mount

`useAssistedTool` looks for the nearest `AssistedPage`. Under one, the tool joins that page's set, and the note lists it. Outside any page, the tool is global: lent on every page and listed in no note. Moving a hook in the tree is how a host scopes a tool.

Actions work the same way, with one more rule. Actions with the same name on one page become one tool. Each row's `id` joins an enum, and the description pairs each id with its label. A table of fifty rows lends one `ship_order`, not fifty tools.

## Leaving is part of the contract

The model's view lags the page. It may call a tool from the last request after the page that lent it has gone. A call that finds nothing would stall the turn. So when a tool leaves, the provider keeps a disabled stand-in under its name. The runtime leaves disabled tools out of what the backend sees, but still runs them for a call that arrives. The stand-in answers "The page no longer offers …" with the note of the page open now.

Answers that may follow a change of page carry the note of the page open now: a press, `go_to_page`, and the stand-in for a tool that left. The universal instructions tell the model that such an answer is newer than the note sent with the message.

## Re-lending only on change

A component re-renders often. Lending a tool again on each render would churn the registry. `useAssistedTool` lends once, and again only when the description or the parameters' JSON Schema changes. `execute` reads a ref to the latest version, so it always sees current state without a new registration.

---

# Parts and the default composition

> Why the panel is made of parts, how containers fall back to their defaults, where parts stop and slots begin, and why the default panel looks the way it does.

The panel comes ready-made: one line renders a header, a conversation and a composer that work with whatever the provider has. It is also made of parts, and the host can move, swap or leave out any of them. This page is about how those two fit.

## Three levels of change

Most apps never go past the first level, and each level costs only what it changes.

- **Use it.** `<AssistedPanel mode="floating" />` and its props: where it sits, what it is called, which threads and models it offers.
- **Rearrange it.** Compose the parts by hand. Move the model picker to the header, drop the attachment button, put a context bar in a footer.
- **Replace a part.** Write your own component against `useAssisted`, `useAui`, `useAuiState` and the primitives, and drop it where the part went.

The panel's source is not a level. There is nothing to copy into your app and keep in step with a release: a part you have not replaced updates with the package.

## Containers fall back to their defaults

A container part with no children renders its default. With children, it renders exactly those and nothing else. So `<AssistedPanel.Header />` is the whole default header, while a `Header` with two children is those two.

This keeps a change local. To trim the composer, you write the composer's children and leave `<AssistedPanel.Header />` and `<AssistedPanel.Conversation />` bare. You never restate a default to keep it.

The one-liner is the same rule one level up: `AssistedPanel` with a `mode` is a root with no children.

## Any part anywhere

Parts read the panel's state from the root above them, not from their parent. A `ModelSelector` works in the header as well as in the composer, and a `ContextDisplay` in a footer as well as in the header. The groups on the Components pages say where a part sits by default, not where it must sit.

The root holds what several parts share: whether the panel is open, the picked model, the thread drawer, the conversation search, the settings. That is why a toggle and the thing it toggles may sit in different containers: `SettingsToggle` in the header swaps `Conversation` for `SettingsPanel` below it.

`Trigger` goes one step further. It reads only the provider's open state, so it sits anywhere under `AssistedProvider`, in the host's own toolbar.

## Your buttons, our behavior

A button part takes `asChild`. With it, the part renders your element and hands it the click, the label and the pressed state. The host's design system keeps its buttons, and the part keeps what the button does.

Only the button a part shows by default is replaced. `Send` with `asChild` replaces the send button, while the stop button that takes its place during a reply stays the package's. A part's behavior is more than one element, and the host replaces only the element it sees.

## Where parts stop and slots begin

Parts end where a single message begins. Inside `Messages`, the panel renders each message, each tool call, each day line, and the host changes them through `components` slots: `AssistantMessage`, `UserMessage`, `DaySeparator`, `ToolFallback` and the groups.

A message is not a place to arrange. It is a sequence of parts the model produced, text, reasoning, tool calls, rendered in order. A slot replaces how one kind of thing renders, which is the change a host wants there. Tool calls have their own seam on top: `cards` on `AssistedProvider` replaces the card of one tool everywhere.

## Why the default looks the way it does

Several default panels were tried in the example shop. The chosen one is quiet:

- **One header row.** The icon, the title and the page line, the thread menu, a new-thread button, a search icon, the devtools when given, the window controls and Close.
- **The model picker in the composer.** It sits beside Send, where the choice applies, and only when the host passes `models`.
- **Threads in a menu.** `threads` alone opens a searchable menu with each thread's preview. A select row and a drawer are the other styles.
- **Search behind an icon.** The conversation search opens from the header and stays out of the way until then.
- **Cards inline.** A card stands in the conversation where the call happened, never folded into a group of tool calls.
- **Settings and usage opt-in.** The settings panel, the context display, the breakdown and the quota banner need data the host may not have, so the host places them.

Underneath is one rule: the default renders only what is real with the provider's data. No model picker without models, no thread menu unless the host says its runtime has a thread list, no devtools button without devtools, no context ring without usage. A part with nothing to show renders nothing, so a bare default never shows a control that does nothing.