@lua-ai-global/app-chat
v1.1.0
Published
The agent pane for a Lua web app: <AgentPane>, the page's chat with the app's own agent, drawn with @lua-ai-global/ui.
Keywords
Readme
@lua-ai-global/app-chat
The agent pane for a Lua web app: <AgentPane>, the page's chat with the app's
own agent. It talks through lua.chat from @lua-ai-global/app-client (the
app's own gateway, the person's own conversation) and draws the answers with
@lua-ai-global/ui: markdown and the ::: blocks agents write for web
surfaces.
Deprecated:
<AgentPaneLayout>,<AgentPane>anduseAgentPane. The agent pane belongs to the platform now. Lua injects it into every app (the embed below) and the desktop's top-bar Chat button opens it. Don't bundle a pane: remove<AgentPaneLayout>(lua apps upgradedoes it) and drive the platform's pane withlua.panefrom@lua-ai-global/app-client:import { lua } from "@lua-ai-global/app-client"; lua.pane.setContext(() => ({ ticketId: currentTicket() })); // was the `context` prop lua.pane.ask(`Summarise ticket ${id}`, { context: { id } }); // was useAgentPane().ask lua.pane.open(); lua.pane.close();They keep working for now, and are documented below for apps that still use them.
Install
npm install @lua-ai-global/app-chat @lua-ai-global/app-client @lua-ai-global/uiPeers: react and react-dom 19, @lua-ai-global/app-client 0.0.3 or later,
@lua-ai-global/ui 0.2 (with its own peers, @base-ui/react and
@phosphor-icons/react). An app made with lua apps new already has them.
The pane is styled with Tailwind utilities on the ui tokens, shipped the same
way as @lua-ai-global/ui: import its stylesheet after the ui one, in the CSS
file Tailwind (v4) compiles.
@import "@lua-ai-global/ui/styles.css";
@import "@lua-ai-global/app-chat/styles.css";
@source "../node_modules/@lua-ai-global/ui/dist";There are no resets or globals. Dark mode follows the .dark class the app
sets from the shell's theme (lua.onInit).
Use (deprecated)
Dock the pane beside the app:
import { AgentPaneLayout } from "@lua-ai-global/app-chat";
createRoot(root).render(
<AgentPaneLayout context={() => ({ ticketId: currentTicket() })}>
<App />
</AgentPaneLayout>,
);The page sits beside the pane and shrinks while it is open; the pane is never
drawn over it. The pane collapses to an edge button, and is a bottom sheet below
768px. Whether it is open is remembered per app (in localStorage, when the
browser allows it).
Or put it where you want it; inline fills its container:
<div className="h-[600px]">
<AgentPane variant="inline" />
</div>Open it, close it, or ask it something from anywhere on the page:
import { useAgentPane } from "@lua-ai-global/app-chat";
function TicketActions({ id }: { id: number }) {
const pane = useAgentPane();
return (
<button onClick={() => pane.ask(`Summarise ticket ${id}`, { context: { id } })}>
Ask the agent
</button>
);
}ask opens the dock and sends the text as the person's next message (once the
pane is ready, if it is still loading). One turn runs at a time: an ask while
a turn is in flight is not sent.
Props
<AgentPane> and <AgentPaneLayout> take the same props (the layout has no
variant; it adds children and layoutClassName).
| Prop | Type | Default | |
| --- | --- | --- | --- |
| variant | "dock" \| "inline" | "dock" | Docked on the right, or filling its container |
| context | unknown \| () => unknown | — | JSON sent with each turn (at most 4096 bytes); a function is read at send time |
| onTurnEnd | (e: { ok, error? }) => void | — | After every turn this page sent settles, as lua.chat.onTurnEnd: refetch what the agent may have changed |
| labels | Partial<AgentPaneLabels> | English | Override any string (DEFAULT_LABELS lists them) |
| workspaceUrl | string | the Workspace shell that framed the app | Where the approval link points |
| storageKey | string | one per app | localStorage key for the dock's open state |
| className | string | — | Classes for the pane |
| chat | LuaChat | lua.chat | The chat to talk to (tests, storybooks) |
useAgentPane() returns { isOpen, open(), close(), ask(text, { context? }) }.
What it draws
- Text is GitHub-flavoured markdown. Raw HTML is never rendered: it shows
as the text it is. Links open in a new tab;
javascript:links are dropped. Code fences (mermaid too) are plain code blocks. - Blocks (parsed by
@lua-ai-global/chat-contract):list-item(stacked cards) andhorizontal-list-item(a card carousel) — tapping a card sends its title and subheading;actions— buttons that send their label as the next message;links;images(a scrollable row);payment(a card whose Pay link opens a new tab);documents(file cards with Open and Download);reaction(the emoji on the person's message). A block still streaming shows a placeholder, never its raw text; an unknown block shows its body as text.formblocks are not drawn (the pane does not declare forms). - History: the latest 50 messages when the pane mounts, oldest first, with "Load earlier messages" for the page before. Images and files show as media; reasoning, tool calls and sources are not shown.
Images and the CSP. A web app's pages load images only from the hosts its
pages.csp allows. Add the hosts your agent's images come from (product
photos, CDNs) to img-src, or the images and card blocks show broken images.
States
| When | The pane |
| --- | --- |
| The app has its agent pane off (agentPane: false) | Renders nothing (one console.info) |
| A preview deployment (PREVIEW_NO_AGENT_PANE) | "Not available in preview", no composer |
| TURN_IN_FLIGHT | "The agent is still replying in another window." + Retry |
| CONCURRENCY_LIMIT, APP_DISABLED | "Try again in N s." (from retryAfter) + Retry |
| STREAM_INTERRUPTED, STREAM_ERROR | What happened + Retry; a partial answer stays |
| FORBIDDEN | "You do not have access to this app's agent." |
| A turn stops for an approval | "This step is waiting for approval in Lua Workspace", linking there |
| The history cannot be read | "The conversation could not be loaded." + Retry |
Retry re-sends the last message (or reads the history again). The approval line
keys on lua-core's approval parts in the stream: data-lua-approval
(status: "required"), data-lua-governance (status: "approval_required"),
data-lua-device-approval, and any other tool-approval-request or
data-*approval* part.
The composer sends on Enter (Shift+Enter is a new line), at most 8000 characters; a counter appears near the limit.
Embed (used by Lua for older apps)
@lua-ai-global/app-chat/embed.js (dist/embed.js) is not for apps to import.
The Lua gateway injects it into web apps built before the pane existed and
serves it same-origin. It is one minified script with its own React, ui
components, markdown and styles, so it never meets the app's.
- The gateway's
<head>script puts a second handoff code inwindow.__LUA_PANE__.code(from#paneCode=…). No code: the script does nothing. Otherwise it signs in with its own client (createLuaClient({ code, purpose: "pane" })), which never speaks the bridge. - It draws into an open Shadow DOM on
<div data-lua-agent-pane>at the end of<body>. Its stylesheet is adopted by the shadow root (a constructable stylesheet, which the app'sstyle-src 'self' 'nonce-…'allows), so nothing lands in the document. - A bottom-right button opens a 380px panel over the right edge (a bottom
sheet below 768px), remembered per app. Light, or the shell's
lua:inittheme. Nothing when the app has its agent pane off. When the pane's session ends it says "Open the app again to use the agent." - Under a host that opens it. The desktop that shows a Chat button in the
app's top bar puts
paneHost=1in the fragment; the head script turns it intowindow.__LUA_PANE__.host === true(heeded only in a frame: a top-level page keeps the launcher). Then there is no button: the panel (same size and place, X and Escape close it, focus goes into it on open) opens and closes only with the shell's{ type: "lua:pane:set", v: 1, open }and the app'slua.pane. It always starts closed, is never remembered, and closes on every page change (pushState/replaceStateto another path,popstate,hashchange). It opens only when the chat is on, and tells the shell{ type: "lua:pane:state", v: 1, availability: "on" | "off" | "ended", open }once availability is known, on every open change, and in answer to eachlua:pane:set. Both messages go to, and come only from, the bootstrap'shostOrigins. Withouthostthe embed is exactly as above. - When the workspace cannot pay for a turn. The agent's sentence shows as
its reply, as always. If the hosting shell lists
"billing-stop"in the latestlua:init'sopens, the pane also posts it{ type: "lua:open", v: 1, target: "billing-stop", unit: "actions" | "credits" }, once per turn whose stream carriesdata-lua-out-of-actionsordata-lua-out-of-credits, so the shell can offer a top-up. Only the unit goes; never for history. A shell that does not list it hears nothing new. - Either way it serves the app's
lua.pane(open,close,ask,setContext), whether the app's client or the embed loaded first.
Every build of the pane, dist/index.js and dist/embed.js (so any app bundle
that draws <AgentPane>), contains the string __lua_agent_pane_v1__
(AGENT_PANE_MARKER). The gateway scans an app's assets for it and injects no
pane into an app that has it. Change it only with the gateway.
Develop
pnpm --filter @lua-ai-global/app-chat test # vitest + Testing Library (jsdom)
pnpm --filter @lua-ai-global/app-chat build # tsup → dist/, then scripts/build-embed.mjs → dist/embed.js