Skip to content

Self-improving AI Employees for everyone

feat(chat): generated UI, follow-ups and citations in replies

trohitg977383cfaafc
diff --git a/client/eslint.config.js b/client/eslint.config.js
index 99e48930..d4f824ad 100644
--- a/client/eslint.config.js
+++ b/client/eslint.config.js
@@ -124,11 +124,19 @@ export default tseslint.config(
],
},
},
- // Tests may set up the chat's internals (its stores, its lazy markdown);
- // they keep the setup-screen rule.
+ // Tests may set up the chat's internals (its stores, its lazy markdown,
+ // its own genui folder); they keep the setup-screen rule.
{
files: ['src/**/__tests__/**/*.{ts,tsx}', 'src/**/*.test.{ts,tsx}'],
ignores: ['src/features/home/genui/**'],
+ rules: {
+ 'no-restricted-imports': ['error', { patterns: [{ group: ['**/home/genui/*'], message: GENUI_PRIVATE }] }],
+ },
+ },
+ // Home's own tests reach the setup screen relatively ("../genui/catalog").
+ {
+ files: ['src/features/home/**/__tests__/**/*.{ts,tsx}', 'src/features/home/**/*.test.{ts,tsx}'],
+ ignores: ['src/features/home/genui/**'],
rules: {
'no-restricted-imports': [
'error',
diff --git a/client/src/features/chat/ChatPane.tsx b/client/src/features/chat/ChatPane.tsx
index 6b4929d0..9444c161 100644
--- a/client/src/features/chat/ChatPane.tsx
+++ b/client/src/features/chat/ChatPane.tsx
@@ -12,14 +12,16 @@
* answer too. A message that does not go comes back into the box.
*/
-import { useCallback, useImperativeHandle, useRef, type KeyboardEvent, type Ref } from 'react';
+import { useCallback, useImperativeHandle, useLayoutEffect, useMemo, useRef, type KeyboardEvent, type Ref } from 'react';
import { cn } from '@/lib/utils';
import { useConversation } from './data/conversation';
import { useSendChatMessage, type ChatSendError } from './data/send';
import { useStopChatRun } from './data/stop';
+import { useUiStateSync } from './data/uiState';
import { Composer } from './composer/Composer';
+import { asksWhatItSays, type ChatUiActions } from './genui/actions';
import type { ChatHost, ChatPaneHandle } from './host';
-import { useComposerStore } from './state/composerStore';
+import { newClientMessageId, useComposerStore } from './state/composerStore';
import { ChatThread } from './thread/ChatThread';
export function ChatPane({ host, ref }: { host: ChatHost; ref?: Ref<ChatPaneHandle> }) {
@@ -51,6 +53,57 @@ export function ChatPane({ host, ref }: { host: ChatHost; ref?: Ref<ChatPaneHand
if (lane && !stopping) stop.mutate(lane);
};
+ // What an interface's buttons do. Read through a ref, so the handlers an
+ // interface made once keep reaching the current pane.
+ const uiState = useUiStateSync(sessionId);
+ const live = useRef({ busy, ready: Boolean(thread.data), send: send.mutate, notify, uiState });
+ useLayoutEffect(() => {
+ live.current = { busy, ready: Boolean(thread.data), send: send.mutate, notify, uiState };
+ });
+ const uiActions = useMemo<ChatUiActions>(
+ () => ({
+ ask: (text, label) => {
+ const pane = live.current;
+ if (asksWhatItSays(text, label) && !pane.busy && pane.ready) {
+ pane.send({ text, clientMessageId: newClientMessageId() });
+ return;
+ }
+ // Not what the button says (or not now): the owner reads it first.
+ useComposerStore.getState().setText(sessionId, text);
+ boxRef.current?.focus();
+ },
+ event: (event) => {
+ const pane = live.current;
+ if (pane.busy || !pane.ready) {
+ pane.notify(`${persona.name} is still answering. Try that again once they finish.`, 'info');
+ return;
+ }
+ pane.uiState.flush(event.partId);
+ pane.send({
+ text: event.label || event.action,
+ clientMessageId: newClientMessageId(),
+ uiEvent: { partId: event.partId, elementId: event.elementId, action: event.action, params: event.params },
+ });
+ },
+ }),
+ [sessionId, persona.name],
+ );
+
+ // A suggested question goes as written; while the last answer is still
+ // coming, it waits in the box instead.
+ const followUp = useCallback(
+ (text: string) => {
+ const pane = live.current;
+ if (!pane.busy && pane.ready) {
+ pane.send({ text, clientMessageId: newClientMessageId() });
+ return;
+ }
+ useComposerStore.getState().setText(sessionId, text);
+ boxRef.current?.focus();
+ },
+ [sessionId],
+ );
+
const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
if (event.key !== 'Escape' || event.defaultPrevented || !lane || stopping) return;
event.preventDefault();
@@ -71,6 +124,9 @@ export function ChatPane({ host, ref }: { host: ChatHost; ref?: Ref<ChatPaneHand
liveNote={host.liveNote}
compact={compact}
canStop={composer !== 'closed'}
+ uiActions={uiActions}
+ onUiStateChange={uiState.change}
+ onFollowUp={composer === 'send' ? followUp : undefined}
onScrolledChange={host.onScrolledChange}
/>
<div className={cn('relative flex-none', compact ? 'border-t border-border-default px-3 py-2' : 'px-6 pb-3')}>
diff --git a/client/src/features/chat/__tests__/chatPane.test.tsx b/client/src/features/chat/__tests__/chatPane.test.tsx
index 0591b9b4..45d135d3 100644
--- a/client/src/features/chat/__tests__/chatPane.test.tsx
+++ b/client/src/features/chat/__tests__/chatPane.test.tsx
@@ -271,6 +271,25 @@ describe('ChatPane', () => {
await waitFor(() => expect(chat.notify).toHaveBeenCalledWith('Couldn’t stop the reply. Try again.', 'error'));
});
+ it('offers the next questions the employee suggested, under its latest answer only', async () => {
+ const followups = ['What about Sunday?', 'Move it to 3pm', 'What about Sunday?', ' '];
+ server.messages = [
+ row('m0', 'user', 'Old question'),
+ row('a0', 'assistant', 'Old answer', { parts: { followups: ['Never shown'] } }),
+ row('m1', 'user', 'Any bookings?', { run_id: 'r1' }),
+ row('a_r1', 'assistant', 'Two today.', { run_id: 'r1', parts: { followups } }),
+ ];
+ renderPane();
+ const group = await screen.findByRole('group', { name: 'Ask next' });
+ expect(group).toHaveTextContent('What about Sunday?Move it to 3pm');
+ expect(screen.queryByText('Never shown')).not.toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Move it to 3pm' }));
+ await waitFor(() =>
+ expect(sendRequest).toHaveBeenCalledWith('send_chat_message', expect.objectContaining({ message: 'Move it to 3pm', session_id: 'w1' })),
+ );
+ });
+
it('says why a run failed, with what to do about it', async () => {
server.messages = [row('m1', 'user', 'Book Priya in', { run_id: 'r1' })];
server.activeRuns = [{ run_id: 'r1', session_id: 'w1', state: 'running', seq: 1, hub_epoch: 'e1' }];
diff --git a/client/src/features/chat/__tests__/chatPaneUi.test.tsx b/client/src/features/chat/__tests__/chatPaneUi.test.tsx
new file mode 100644
index 00000000..63b3b017
--- /dev/null
+++ b/client/src/features/chat/__tests__/chatPaneUi.test.tsx
@@ -0,0 +1,185 @@
+/**
+ * An interface the employee shows in its reply, against a fake server: it
+ * streams in with the run, its buttons ask (sending only what they say) or
+ * go back to the employee once the answer is done, what the owner sets goes
+ * to the server after a pause, and the saved reply keeps it.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const sendRequest = vi.fn();
+
+vi.mock('@/contexts/WebSocketContext', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@/contexts/WebSocketContext')>()),
+ useWebSocketActions: () => ({ sendRequest, isReady: true, addEventListener: () => () => {} }),
+}));
+// Everything shows at once, as under reduced motion.
+vi.mock('@/lib/motion', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@/lib/motion')>()),
+ motionSuppressed: () => true,
+}));
+
+import { resetChatRunStore, useChatRunStore } from '@/stores/chatRunStore';
+import booking from '../__fixtures__/saturday-booking.spec.json';
+import { ChatPane } from '../ChatPane';
+import type { ChatHost } from '../host';
+import { useComposerStore } from '../state/composerStore';
+// Loaded up front so the lazy chunks resolve from the module cache.
+import '../genui/ChatUi';
+import '../markdown/ReplyMarkdown';
+
+type Wire = Record<string, unknown>;
+let server: { messages: Wire[]; activeRuns: Wire[] };
+let client: QueryClient;
+
+function row(id: string, role: 'user' | 'assistant', text: string, patch: Wire = {}): Wire {
+ return { id, role, text, message: text, timestamp: '2026-10-04T09:00:00Z', run_key: 'g1', ...patch };
+}
+
+function frame(seq: number, suffix: string, data: Wire = {}, runId = 'r1') {
+ return {
+ specversion: '1.0',
+ id: `${runId}:${seq}`,
+ source: 'opencompany://services/chat',
+ type: `com.opencompany.chat.run.${suffix}`,
+ subject: runId,
+ data: { workflow_id: 'w1', session_id: 'w1', run_id: runId, seq, hub_epoch: 'e1', ...data },
+ };
+}
+
+function runEvents(...frames: unknown[]) {
+ act(() => {
+ const store = useChatRunStore.getState();
+ for (const item of frames) store.receive(item);
+ store.flush();
+ });
+}
+
+/** The booking interface as the server streams it: a snapshot, then a patch per step. */
+function uiFrames(firstSeq: number) {
+ const patches: Wire[] = [
+ { op: 'add', path: '/root', value: booking.root },
+ { op: 'add', path: '/state', value: booking.state },
+ ...Object.entries(booking.elements).map(([id, element]) => ({ op: 'add', path: `/elements/${id}`, value: element })),
+ ];
+ return [
+ frame(firstSeq, 'activity.snapshot', { message_id: 'ui_1', activity_type: 'json_render', content: { root: '', state: {}, elements: {} }, replace: true }),
+ ...patches.map((patch, index) => frame(firstSeq + 1 + index, 'activity.delta', { message_id: 'ui_1', activity_type: 'json_render', patch: [patch] })),
+ ];
+}
+
+function host(patch: Partial<ChatHost> = {}): ChatHost {
+ return { kind: 'home', sessionId: 'w1', scope: 'all', persona: { name: 'Maya', colorRole: 'agent' }, composer: 'send', notify: vi.fn(), ...patch };
+}
+
+function renderPane(chat: ChatHost = host()) {
+ client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ return render(
+ <QueryClientProvider client={client}>
+ <ChatPane host={chat} />
+ </QueryClientProvider>,
+ );
+}
+
+beforeEach(() => {
+ resetChatRunStore();
+ useComposerStore.setState({ drafts: {} });
+ server = { messages: [row('m1', 'user', 'Book Priya on Saturday', { run_id: 'r1' })], activeRuns: [{ run_id: 'r1', session_id: 'w1', state: 'running', seq: 1, hub_epoch: 'e1' }] };
+ sendRequest.mockReset().mockImplementation(async (kind: string, data: Wire) => {
+ switch (kind) {
+ case 'chat_subscribe':
+ return { success: true, session_id: data.session_id, hub_epoch: 'e1', active_runs: server.activeRuns };
+ case 'get_chat_messages':
+ return { success: true, messages: server.messages, thread: { active_leaf_id: null, revision: 1 }, active_runs: server.activeRuns };
+ case 'send_chat_message':
+ return { success: true, message_id: 'm2', run_id: 'r2', delivery: 'now' };
+ case 'chat_ui_state':
+ return { success: true, part_id: data.part_id, state_revision: 1 };
+ default:
+ return { success: true };
+ }
+ });
+});
+
+async function finishRun() {
+ server.activeRuns = [];
+ server.messages = [
+ ...server.messages,
+ row('a_r1', 'assistant', 'Saturday has a clean gap with Ana.', {
+ run_id: 'r1',
+ parts: { ui: [{ part_id: 'ui_1', spec: booking, state: booking.state, state_revision: 0, elements: 11 }] },
+ }),
+ ];
+ runEvents(frame(16, 'finished', { outcome: { type: 'success' }, result: { reply_message_id: 'a_r1' } }));
+ await act(async () => {
+ await client.invalidateQueries({ queryKey: ['chatThread'] });
+ });
+ await screen.findByText('Saturday has a clean gap with Ana.');
+}
+
+describe('an interface in a reply', () => {
+ it('streams in with the run and stays once the reply is saved', async () => {
+ renderPane();
+ await screen.findByText('Thinking');
+ runEvents(...uiFrames(2));
+ expect(await screen.findByRole('radiogroup', { name: 'Saturday 28 Sep' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Hold this slot for 15 min' })).toBeInTheDocument();
+ // The Callout waits for its condition.
+ expect(screen.queryByText(/Highlights take about 3 hours/)).not.toBeInTheDocument();
+
+ const picker = screen.getByRole('radiogroup', { name: 'Saturday 28 Sep' });
+ await finishRun();
+ // The same element: the saved reply took over without redrawing it.
+ expect(screen.getByRole('radiogroup', { name: 'Saturday 28 Sep' })).toBe(picker);
+ });
+
+ it('sends what the owner sets after a pause, and shows what depends on it', async () => {
+ renderPane();
+ await screen.findByText('Thinking');
+ runEvents(...uiFrames(2));
+ fireEvent.click(await screen.findByRole('radio', { name: 'Highlights' }));
+ expect(await screen.findByText(/Highlights take about 3 hours/)).toBeInTheDocument();
+ await waitFor(() =>
+ expect(sendRequest).toHaveBeenCalledWith('chat_ui_state', {
+ session_id: 'w1',
+ part_id: 'ui_1',
+ changes: [{ path: '/service', value: 'Highlights' }],
+ }),
+ );
+ });
+
+ it('puts an ask that is not what its button says into the box', async () => {
+ renderPane();
+ await screen.findByText('Thinking');
+ runEvents(...uiFrames(2));
+ fireEvent.click(await screen.findByRole('button', { name: 'Show Sunday instead' }));
+ expect(screen.getByRole('textbox', { name: 'Message Maya' })).toHaveValue('What does Sunday look like?');
+ expect(sendRequest).not.toHaveBeenCalledWith('send_chat_message', expect.anything());
+ });
+
+ it('sends a press back to the employee once the answer is done', async () => {
+ const chat = host();
+ renderPane(chat);
+ await screen.findByText('Thinking');
+ runEvents(...uiFrames(2));
+ fireEvent.click(await screen.findByRole('button', { name: 'Hold this slot for 15 min' }));
+ // Still answering: the press waits.
+ expect(chat.notify).toHaveBeenCalledWith('Maya is still answering. Try that again once they finish.', 'info');
+
+ await finishRun();
+ fireEvent.click(screen.getByRole('button', { name: 'Hold this slot for 15 min' }));
+ // The owner's side reads as the press.
+ expect(await screen.findByText('Pressed')).toHaveClass('sr-only');
+ await waitFor(() =>
+ expect(sendRequest).toHaveBeenCalledWith(
+ 'send_chat_message',
+ expect.objectContaining({
+ message: 'Hold this slot for 15 min',
+ ui_event: { part_id: 'ui_1', element_id: 'hold', action: 'holdSlot', params: { slot: 's2' } },
+ }),
+ ),
+ );
+ });
+});
diff --git a/client/src/features/chat/__tests__/citations.test.tsx b/client/src/features/chat/__tests__/citations.test.tsx
new file mode 100644
index 00000000..46f314c5
--- /dev/null
+++ b/client/src/features/chat/__tests__/citations.test.tsx
@@ -0,0 +1,97 @@
+/**
+ * Citations and sources in an answer: `[n]` of a source the reply has reads
+ * as a chip numbered in the order the reply cites (code left alone), the
+ * cited sources are listed under the answer, and a reply with no sources is
+ * drawn as written.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { savedSources } from '../data/parts';
+import ReplyMarkdown from '../markdown/ReplyMarkdown';
+import { CitationContext } from '../markdown/citationContext';
+import { citationOrder, citedNumber, linkCitations } from '../markdown/citations';
+import { SourceChips } from '../turns/SourceChips';
+
+const known = new Set([7, 9, 12]);
+
+describe('citations', () => {
+ it('numbers cited sources in the order the text first cites them', () => {
+ const order = citationOrder('Ana is free [9]. Jordan too [7][9]. Not a source [3].', known);
+ expect([...order]).toEqual([
+ [9, 1],
+ [7, 2],
+ ]);
+ });
+
+ it('links citations outside code only, and leaves real links alone', () => {
+ const text = 'See [7] and `[9]` and\n```\n[12]\n```\n[link](https://x.test) [12](https://y.test) [3]';
+ expect(linkCitations(text, known)).toBe(
+ 'See [7](#cite-7) and `[9]` and\n```\n[12]\n```\n[link](https://x.test) [12](https://y.test) [3]',
+ );
+ expect(linkCitations('Plain [7]', new Set())).toBe('Plain [7]');
+ expect(citationOrder('`[7]` only in code', known).size).toBe(0);
+ });
+
+ it('reads a citation link back', () => {
+ expect(citedNumber('#cite-12')).toBe(12);
+ expect(citedNumber('#cite-x')).toBeNull();
+ expect(citedNumber('https://x.test')).toBeNull();
+ expect(citedNumber(undefined)).toBeNull();
+ });
+});
+
+describe('savedSources', () => {
+ it('keeps one usable source per number', () => {
+ expect(
+ savedSources({
+ sources: [
+ { n: 7, title: 'Salon hours', url: 'https://salon.test/hours' },
+ { n: 7, title: 'Duplicate' },
+ { n: 8, title: '', url: 'javascript:alert(1)' },
+ { n: 0, title: 'Bad number' },
+ 'nope',
+ ],
+ }),
+ ).toEqual([
+ { n: 7, title: 'Salon hours', url: 'https://salon.test/hours', detail: null },
+ { n: 8, title: 'Source 8', url: null, detail: null },
+ ]);
+ });
+});
+
+describe('a reply that cites', () => {
+ const sources = new Map([
+ [7, { n: 7, title: 'Salon hours', url: 'https://www.salon.test/hours', detail: null }],
+ [9, { n: 9, title: 'Ana’s calendar', url: 'https://cal.test/ana', detail: null }],
+ ]);
+ const order = new Map([
+ [9, 1],
+ [7, 2],
+ ]);
+
+ it('draws each citation as a chip with the reply’s number', () => {
+ render(
+ <CitationContext.Provider value={{ sources, order }}>
+ <ReplyMarkdown text="Ana is free [9], the salon opens at 9 [7]. Elsewhere [3]." />
+ </CitationContext.Provider>,
+ );
+ const ana = screen.getByRole('link', { name: 'Source 1: Ana’s calendar (cal.test)' });
+ expect(ana).toHaveTextContent('1');
+ expect(ana).toHaveAttribute('href', 'https://cal.test/ana');
+ expect(ana).toHaveAttribute('target', '_blank');
+ expect(screen.getByRole('link', { name: 'Source 2: Salon hours (salon.test)' })).toHaveTextContent('2');
+ expect(screen.getByText(/Elsewhere \[3\]\./)).toBeInTheDocument();
+ });
+
+ it('lists the cited sources under the answer, in the same order', () => {
+ render(<SourceChips sources={sources} order={order} />);
+ const items = within(screen.getByRole('list', { name: 'Sources' })).getAllByRole('link');
+ expect(items.map((item) => item.textContent)).toEqual(['1cal.testAna’s calendar', '2salon.testSalon hours']);
+ });
+
+ it('draws a reply without sources as written', () => {
+ render(<ReplyMarkdown text="Nothing cited [1]." />);
+ expect(screen.getByText('Nothing cited [1].')).toBeInTheDocument();
+ });
+});
diff --git a/client/src/features/chat/__tests__/genuiActions.test.ts b/client/src/features/chat/__tests__/genuiActions.test.ts
new file mode 100644
index 00000000..446d5542
--- /dev/null
+++ b/client/src/features/chat/__tests__/genuiActions.test.ts
@@ -0,0 +1,94 @@
+/**
+ * A reply's interface made ready to draw (genui/prepare.ts) and what its
+ * buttons do (genui/actions.ts): unknown components are left out, each
+ * button's press is tagged with its element and label, `ask` sends only what
+ * the button says, and any other action goes back to the employee.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import booking from '../__fixtures__/saturday-booking.spec.json';
+import { asksWhatItSays, chatActionHandlers, type ChatUiActions } from '../genui/actions';
+import { PRESS_ELEMENT, PRESS_LABEL, prepareChatSpec, untagged } from '../genui/prepare';
+
+describe('prepareChatSpec', () => {
+ it('keeps the handoff example and tags each press with its element and label', () => {
+ const spec = prepareChatSpec(booking);
+ expect(spec?.root).toBe('root');
+ expect(Object.keys(spec?.elements ?? {})).toEqual(Object.keys(booking.elements));
+ expect(spec?.elements.hold.on?.press).toEqual({
+ action: 'holdSlot',
+ params: { slot: { $state: '/slot' }, [PRESS_ELEMENT]: 'hold', [PRESS_LABEL]: 'Hold this slot for 15 min' },
+ });
+ });
+
+ it('leaves out components the chat does not have, and children naming them', () => {
+ const spec = prepareChatSpec({
+ root: 'root',
+ state: {},
+ elements: {
+ root: { type: 'Stack', props: {}, children: ['t', 'x', 'later'] },
+ t: { type: 'Text', props: { text: 'hi' } },
+ x: { type: 'Marquee', props: {} },
+ },
+ });
+ expect(Object.keys(spec?.elements ?? {})).toEqual(['root', 't']);
+ // A child not here yet may still be on its way.
+ expect(spec?.elements.root.children).toEqual(['t', 'later']);
+ });
+
+ it('draws nothing until the root has arrived', () => {
+ expect(prepareChatSpec({ root: '', state: {}, elements: {} })).toBeNull();
+ expect(prepareChatSpec({ root: 'root', state: {}, elements: {} })).toBeNull();
+ expect(prepareChatSpec('nope')).toBeNull();
+ });
+
+ it('reads a press back without its tags', () => {
+ expect(untagged({ slot: 's2', [PRESS_ELEMENT]: 'hold', [PRESS_LABEL]: 'Hold' })).toEqual({
+ elementId: 'hold',
+ label: 'Hold',
+ params: { slot: 's2' },
+ });
+ });
+});
+
+describe('chatActionHandlers', () => {
+ function handlers() {
+ const actions: ChatUiActions = { ask: vi.fn(), event: vi.fn() };
+ return { actions, handlers: chatActionHandlers('ui_1', () => actions) };
+ }
+
+ it('sends ask with its text and the label to compare it with', () => {
+ const { actions, handlers: h } = handlers();
+ h.ask({ text: ' What does Sunday look like? ', [PRESS_ELEMENT]: 'sun', [PRESS_LABEL]: 'Show Sunday instead' });
+ expect(actions.ask).toHaveBeenCalledWith('What does Sunday look like?', 'Show Sunday instead');
+ h.ask({ text: '' });
+ expect(actions.ask).toHaveBeenCalledTimes(1);
+ });
+
+ it('sends any other action back to the employee, naming the press', () => {
+ const { actions, handlers: h } = handlers();
+ h.holdSlot({ slot: 's2', [PRESS_ELEMENT]: 'hold', [PRESS_LABEL]: 'Hold this slot for 15 min' });
+ expect(actions.event).toHaveBeenCalledWith({
+ partId: 'ui_1',
+ elementId: 'hold',
+ action: 'holdSlot',
+ params: { slot: 's2' },
+ label: 'Hold this slot for 15 min',
+ });
+ });
+
+ it('answers no name json-render runs itself or that is not an action', () => {
+ const { handlers: h } = handlers();
+ for (const name of ['setState', 'push', 'validateForm', 'then', 'toString', 'constructor', '__proto__', '9lives']) {
+ expect(h[name], name).toBeUndefined();
+ }
+ });
+});
+
+describe('asksWhatItSays', () => {
+ it('compares the text with the label, ignoring case and spacing', () => {
+ expect(asksWhatItSays('Show Sunday', ' show sunday ')).toBe(true);
+ expect(asksWhatItSays('What does Sunday look like?', 'Show Sunday instead')).toBe(false);
+ expect(asksWhatItSays('', '')).toBe(false);
+ });
+});
diff --git a/client/src/features/chat/__tests__/genuiCatalog.test.ts b/client/src/features/chat/__tests__/genuiCatalog.test.ts
new file mode 100644
index 00000000..4da3fc90
--- /dev/null
+++ b/client/src/features/chat/__tests__/genuiCatalog.test.ts
@@ -0,0 +1,88 @@
+/**
+ * The chat catalogue (genui/catalog.ts) against the server's manifest
+ * (server/config/chat_genui_catalog.json), which the server checks every
+ * spec against: the same components, roles, children, bound props, events,
+ * actions and limits. The server's tests read this side the same way.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+ BIND_PROPS,
+ CHAT_ACTIONS,
+ CHAT_COMPONENT_TYPES,
+ CHAT_LIMITS,
+ CHAT_PROP_SCHEMAS,
+ COMPONENT_CHILDREN,
+ COMPONENT_EVENTS,
+ COMPONENT_ROLES,
+ allowedParents,
+} from '../genui/catalog';
+
+interface ManifestComponent {
+ role: string;
+ children?: 'any' | string[];
+ bind?: string;
+ events?: string[];
+ props: { properties?: Record<string, unknown> };
+}
+
+const manifest = JSON.parse(readFileSync(resolve(__dirname, '../../../../../server/config/chat_genui_catalog.json'), 'utf-8')) as {
+ limits: Record<string, number>;
+ components: Record<string, ManifestComponent>;
+ actions: Record<string, unknown>;
+};
+
+describe('the chat catalogue', () => {
+ it('has the manifest’s components, in its order', () => {
+ expect([...CHAT_COMPONENT_TYPES]).toEqual(Object.keys(manifest.components));
+ });
+
+ it('agrees on roles, children, bound props and events', () => {
+ for (const type of CHAT_COMPONENT_TYPES) {
+ const component = manifest.components[type];
+ expect(COMPONENT_ROLES[type], type).toBe(component.role);
+ expect((COMPONENT_CHILDREN as Record<string, unknown>)[type] ?? null, type).toEqual(component.children ?? null);
+ expect((BIND_PROPS as Record<string, unknown>)[type] ?? null, type).toBe(component.bind ?? null);
+ expect((COMPONENT_EVENTS as Record<string, unknown>)[type] ?? null, type).toEqual(component.events ?? null);
+ }
+ });
+
+ it('reads every prop the manifest declares', () => {
+ for (const type of CHAT_COMPONENT_TYPES) {
+ const declared = Object.keys(manifest.components[type].props.properties ?? {}).sort();
+ expect(Object.keys(CHAT_PROP_SCHEMAS[type].shape).sort(), type).toEqual(declared);
+ }
+ });
+
+ it('agrees on actions and limits', () => {
+ expect([...CHAT_ACTIONS].sort()).toEqual(Object.keys(manifest.actions).sort());
+ expect(CHAT_LIMITS).toEqual({
+ maxElements: manifest.limits.max_elements,
+ maxDepth: manifest.limits.max_depth,
+ maxBytes: manifest.limits.max_bytes,
+ maxChildren: manifest.limits.max_children,
+ maxIdLength: manifest.limits.max_id_length,
+ maxPathSegments: manifest.limits.max_path_segments,
+ });
+ });
+
+ it('places a component only where a layout may hold it', () => {
+ expect(allowedParents('Button')).toEqual([null, 'Stack', 'Row']);
+ expect(allowedParents('Select')).toEqual([null, 'Stack', 'Card']);
+ expect(allowedParents('SlotPicker')).toEqual([null, 'Stack']);
+ });
+
+ it('degrades an odd prop instead of failing the element', () => {
+ expect(CHAT_PROP_SCHEMAS.Select.parse({ label: 'Service', options: ['A', 'A', 7, null, 'B'] })).toEqual({
+ label: 'Service',
+ options: ['A', '7', 'B'],
+ });
+ expect(CHAT_PROP_SCHEMAS.Callout.parse({ tone: 'neon', text: 'Heads up' })).toEqual({ tone: 'info', text: 'Heads up' });
+ expect(CHAT_PROP_SCHEMAS.BarChart.parse({ title: 'Replies', bars: [{ label: 'Mon', value: -3 }, { label: 'Tue', value: '4' }] }).bars).toEqual([
+ { label: 'Mon', value: 0 },
+ { label: 'Tue', value: 4 },
+ ]);
+ });
+});
diff --git a/client/src/features/chat/__tests__/model.test.ts b/client/src/features/chat/__tests__/model.test.ts
index 7db1c092..c7cc42e5 100644
--- a/client/src/features/chat/__tests__/model.test.ts
+++ b/client/src/features/chat/__tests__/model.test.ts
@@ -179,3 +179,17 @@ describe('buildTurns', () => {
expect(answer.kind === 'assistant' && answer.work).toEqual({ steps: withSteps.steps, live: false, durationMs: 8_000 });
});
});
+
+describe('sources on the thread', () => {
+ it('gives each answer the conversation’s sources so far, so it may cite an older one', () => {
+ const first = message('a1', 'assistant', { parts: { sources: [{ n: 1, title: 'Bloom', url: 'https://bloom.test/' }] } });
+ const plain = message('a2', 'assistant');
+ const second = message('a3', 'assistant', { parts: { sources: [{ n: 2, title: 'Stem', url: 'https://stem.test/' }] } });
+ const turns = buildTurns([message('u1', 'user'), first, plain, second], {});
+ const known = turns.flatMap((turn) => (turn.kind === 'assistant' ? [[...turn.sources.keys()]] : []));
+ expect(known).toEqual([[1], [1], [1, 2]]);
+ // An answer that adds none shares the map before it.
+ const [a1, a2] = turns.filter((turn) => turn.kind === 'assistant');
+ expect(a1.kind === 'assistant' && a2.kind === 'assistant' && a1.sources === a2.sources).toBe(true);
+ });
+});
diff --git a/client/src/features/chat/data/parts.ts b/client/src/features/chat/data/parts.ts
new file mode 100644
index 00000000..07a8fb38
--- /dev/null
+++ b/client/src/features/chat/data/parts.ts
@@ -0,0 +1,83 @@
+/**
+ * What a reply shows besides its text (docs-internal/chat_protocol.md,
+ * "Messages"): its parts. A saved reply carries them in `parts`; a run still
+ * going builds them through its `activity.*` events. Read forgivingly: a
+ * part this client cannot read is left out.
+ */
+
+import type { RunActivity } from '@/lib/agui/reduceRun';
+
+/** A generated UI, saved or arriving. */
+export interface UiPart {
+ partId: string;
+ /** json-render's flat spec, as the server checked it. */
+ spec: unknown;
+ /** What the owner last set; null when it is the spec's own. */
+ state: Record<string, unknown> | null;
+ stateRevision: number;
+ /** Patches folded in so far, for a UI arriving now. */
+ patches: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The generated UIs of a saved reply's `parts`. */
+export function savedUiParts(parts: Record<string, unknown> | null | undefined): UiPart[] {
+ const raw = parts?.ui;
+ if (!Array.isArray(raw)) return [];
+ return raw.flatMap((item) => {
+ if (!isRecord(item) || typeof item.part_id !== 'string' || !item.part_id || !isRecord(item.spec)) return [];
+ return [
+ {
+ partId: item.part_id,
+ spec: item.spec,
+ state: isRecord(item.state) ? item.state : null,
+ stateRevision: typeof item.state_revision === 'number' ? item.state_revision : 0,
+ patches: 0,
+ },
+ ];
+ });
+}
+
+/** A source a tool gave the employee, numbered in the conversation. */
+export interface SourceItem {
+ n: number;
+ title: string;
+ url: string | null;
+ detail: string | null;
+}
+
+/** The sources a saved reply drew on (`parts.sources`), one per number. */
+export function savedSources(parts: Record<string, unknown> | null | undefined): SourceItem[] {
+ const raw = parts?.sources;
+ if (!Array.isArray(raw)) return [];
+ const seen = new Set<number>();
+ return raw.flatMap((item) => {
+ if (!isRecord(item) || typeof item.n !== 'number' || !Number.isInteger(item.n) || item.n < 1 || seen.has(item.n)) return [];
+ seen.add(item.n);
+ const url = typeof item.url === 'string' && /^https?:\/\//i.test(item.url) ? item.url : null;
+ const title = typeof item.title === 'string' && item.title.trim() ? item.title.trim() : (url ?? `Source ${item.n}`);
+ const detail = typeof item.detail === 'string' && item.detail.trim() ? item.detail.trim() : null;
+ return [{ n: item.n, title, url, detail }];
+ });
+}
+
+/** What the employee suggested the owner ask next: at most three short
+ * questions, blanks and repeats left out. */
+export function savedFollowups(parts: Record<string, unknown> | null | undefined): string[] {
+ const raw = parts?.followups;
+ if (!Array.isArray(raw)) return [];
+ const items = raw.flatMap((item) => (typeof item === 'string' && item.trim() ? [item.trim().slice(0, 160)] : []));
+ return [...new Set(items)].slice(0, 3);
+}
+
+/** The generated UIs a run is streaming. */
+export function liveUiParts(activities: readonly RunActivity[] | undefined): UiPart[] {
+ return (activities ?? []).flatMap((activity) =>
+ activity.activityType === 'json_render' && isRecord(activity.content)
+ ? [{ partId: activity.messageId, spec: activity.content, state: null, stateRevision: 0, patches: activity.patches }]
+ : [],
+ );
+}
diff --git a/client/src/features/chat/data/send.ts b/client/src/features/chat/data/send.ts
index 5616d2e0..2648a569 100644
--- a/client/src/features/chat/data/send.ts
+++ b/client/src/features/chat/data/send.ts
@@ -55,6 +55,19 @@ type SendReply = {
delivery?: string;
};
+/** A button pressed in an interface the employee showed: sent back to it
+ * as the owner's next turn (`send_chat_message`'s `ui_event`). */
+export interface UiEventSend {
+ partId: string;
+ elementId: string;
+ action: string;
+ params: Record<string, unknown>;
+}
+
+/** What one send carries: the text shown as the owner's message, and for a
+ * button press, the press. */
+export type SendDraft = TakenDraft & { uiEvent?: UiEventSend };
+
function localId(clientMessageId: string): string {
return `local:${clientMessageId}`;
}
@@ -67,8 +80,8 @@ export function useSendChatMessage(sessionId: string, scope: ThreadScope, onRefu
const replace = (update: (messages: ChatMessage[]) => ChatMessage[]) =>
queryClient.setQueryData<ChatThreadData>(key, (data) => (data ? { ...data, messages: update(data.messages) } : data));
- return useMutation<SendResult, ChatSendError, TakenDraft>({
- mutationFn: async ({ text, clientMessageId }) => {
+ return useMutation<SendResult, ChatSendError, SendDraft>({
+ mutationFn: async ({ text, clientMessageId, uiEvent }) => {
let reply: SendReply | undefined;
try {
reply = await sendRequest<SendReply>('send_chat_message', {
@@ -77,6 +90,16 @@ export function useSendChatMessage(sessionId: string, scope: ThreadScope, onRefu
role: 'user',
timestamp: new Date().toISOString(),
client_message_id: clientMessageId,
+ ...(uiEvent
+ ? {
+ ui_event: {
+ part_id: uiEvent.partId,
+ element_id: uiEvent.elementId,
+ action: uiEvent.action,
+ params: uiEvent.params,
+ },
+ }
+ : {}),
});
} catch {
throw new ChatSendError('transport', { transport: true });
@@ -90,13 +113,13 @@ export function useSendChatMessage(sessionId: string, scope: ThreadScope, onRefu
delivery: reply.delivery === 'queued' ? 'queued' : reply.delivery === 'now' ? 'now' : null,
};
},
- onMutate: async ({ text, clientMessageId }) => {
+ onMutate: async ({ text, clientMessageId, uiEvent }) => {
await queryClient.cancelQueries({ queryKey: key });
const pending: ChatMessage = {
id: localId(clientMessageId),
legacyId: null,
role: 'user',
- kind: 'text',
+ kind: uiEvent ? 'action' : 'text',
text,
timestamp: new Date().toISOString(),
runKey: null,
@@ -129,7 +152,8 @@ export function useSendChatMessage(sessionId: string, scope: ThreadScope, onRefu
},
onError: (error, draft) => {
replace((messages) => messages.filter((message) => message.id !== localId(draft.clientMessageId)));
- useComposerStore.getState().restore(sessionId, draft, error.transport);
+ // A button press is not the owner's writing: nothing goes back in the box.
+ if (!draft.uiEvent) useComposerStore.getState().restore(sessionId, draft, error.transport);
onRefused?.(error);
},
// The refetch swaps the local copy for the saved row.
diff --git a/client/src/features/chat/data/uiState.ts b/client/src/features/chat/data/uiState.ts
new file mode 100644
index 00000000..dee0a3a7
--- /dev/null
+++ b/client/src/features/chat/data/uiState.ts
@@ -0,0 +1,91 @@
+/**
+ * Telling the employee what the owner set in an interface it showed
+ * (`chat_ui_state`, docs-internal/chat_protocol.md). Changes to one
+ * interface coalesce per state path (the last value wins) and go out 300 ms
+ * after the owner stops, when the page hides, when the chat closes, and
+ * before a press of one of its buttons goes. The server keeps them on the
+ * reply, so a reload shows them, and tells the employee on its next turn.
+ *
+ * Best effort: a change that does not reach the server is sent again with
+ * the next one.
+ */
+
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useWebSocketActions } from '@/contexts/WebSocketContext';
+import type { UiStateChange } from '@/lib/jsonRender/uiState';
+
+/** How long the owner pauses before changes go. */
+export const UI_STATE_IDLE_MS = 300;
+
+export interface UiStateSync {
+ /** Record changes to one interface's state. */
+ change: (partId: string, changes: UiStateChange[]) => void;
+ /** Send what is waiting now: for one interface, or for all. */
+ flush: (partId?: string) => void;
+}
+
+export function useUiStateSync(sessionId: string): UiStateSync {
+ const { sendRequest } = useWebSocketActions();
+ const pending = useRef(new Map<string, Map<string, unknown>>());
+ const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+ const send = useCallback(
+ (partId: string) => {
+ const waiting = pending.current.get(partId);
+ if (!waiting || waiting.size === 0) return;
+ pending.current.delete(partId);
+ const changes = [...waiting].map(([path, value]) => ({ path, value }));
+ sendRequest('chat_ui_state', { session_id: sessionId, part_id: partId, changes }).catch(() => {
+ // Not lost: what failed goes again with the next change, unless a
+ // newer value for the same path is already waiting.
+ const again = pending.current.get(partId) ?? new Map<string, unknown>();
+ for (const { path, value } of changes) if (!again.has(path)) again.set(path, value);
+ pending.current.set(partId, again);
+ });
+ },
+ [sessionId, sendRequest],
+ );
+
+ const flush = useCallback(
+ (partId?: string) => {
+ if (timer.current !== null) {
+ clearTimeout(timer.current);
+ timer.current = null;
+ }
+ if (partId !== undefined) send(partId);
+ for (const id of [...pending.current.keys()]) send(id);
+ },
+ [send],
+ );
+
+ const change = useCallback(
+ (partId: string, changes: UiStateChange[]) => {
+ if (changes.length === 0) return;
+ const waiting = pending.current.get(partId) ?? new Map<string, unknown>();
+ for (const { path, value } of changes) {
+ waiting.delete(path);
+ waiting.set(path, value);
+ }
+ pending.current.set(partId, waiting);
+ if (timer.current !== null) clearTimeout(timer.current);
+ timer.current = setTimeout(() => {
+ timer.current = null;
+ flush();
+ }, UI_STATE_IDLE_MS);
+ },
+ [flush],
+ );
+
+ useEffect(() => {
+ const onHide = () => {
+ if (document.visibilityState === 'hidden') flush();
+ };
+ document.addEventListener('visibilitychange', onHide);
+ return () => {
+ document.removeEventListener('visibilitychange', onHide);
+ flush();
+ };
+ }, [flush]);
+
+ return useMemo(() => ({ change, flush }), [change, flush]);
+}
diff --git a/client/src/features/chat/genui/ChatUi.tsx b/client/src/features/chat/genui/ChatUi.tsx
new file mode 100644
index 00000000..8a0ec75a
--- /dev/null
+++ b/client/src/features/chat/genui/ChatUi.tsx
@@ -0,0 +1,95 @@
+/**
+ * One interface an employee showed in a reply, drawn by json-render from the
+ * chat catalogue (registry.ts). The reply turn loads it lazily
+ * (turns/GeneratedUiBlock.tsx), so json-render stays out of the chat's
+ * first chunk.
+ *
+ * - **Arriving.** While the run streams it (`live`), the elements appear one
+ * at a time (REVEAL_STEP_MS each, all at once under reduced motion or on a
+ * hidden page) and each rises in once. The count only moves forward, so
+ * patches that land in several bursts never restart it. A UI read back
+ * later shows at once, without motion.
+ * - **State.** It keeps its own state store (lib/jsonRender/uiState.ts),
+ * seeded from what the owner last set (`state`) or the spec's own, and
+ * reports every change to `onStateChange`.
+ * - **Buttons** run the chat's actions (genui/actions.ts); `setState` is
+ * json-render's own.
+ */
+
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { Spec } from '@json-render/core';
+import { JSONUIProvider, Renderer } from '@json-render/react';
+import { LiveUiContext, REVEAL_STEP_MS, createUiStateStore, specFromPatches, specToPatches, type UiStateChange } from '@/lib/jsonRender';
+import { motionSuppressed } from '@/lib/motion';
+import { chatActionHandlers, type ChatUiActions } from './actions';
+import { prepareChatSpec } from './prepare';
+import { chatRegistry } from './registry';
+
+/** `add /root` and `add /state`, ahead of the elements. */
+const HEAD = 2;
+
+export interface ChatUiProps {
+ partId: string;
+ /** The spec as the run or the saved reply has it. */
+ spec: unknown;
+ /** What the owner last set, when the reply was saved with it. */
+ state?: Record<string, unknown> | null;
+ live: boolean;
+ actions: ChatUiActions;
+ onStateChange?: (changes: UiStateChange[]) => void;
+}
+
+/** Unknown types are left out by prepareChatSpec; anything else renders nothing. */
+function NoElement() {
+ return null;
+}
+
+/** How many of `total` elements show: forward only, paced from when the
+ * first one showed. */
+function useForwardReveal(total: number, live: boolean): number {
+ const [shown, setShown] = useState(() => (!live || motionSuppressed() ? Number.POSITIVE_INFINITY : 1));
+ const started = useRef<number | null>(null);
+
+ useEffect(() => {
+ if (shown >= total) return;
+ const since = started.current ?? performance.now();
+ started.current = since;
+ const timer = window.setInterval(() => {
+ const due = motionSuppressed() ? total : Math.floor((performance.now() - since) / REVEAL_STEP_MS) + 1;
+ setShown((current) => Math.max(current, Math.min(total, due)));
+ }, REVEAL_STEP_MS);
+ return () => window.clearInterval(timer);
+ }, [shown, total]);
+ return Math.min(total, shown);
+}
+
+function ChatUiBody({ partId, spec, state, live, actions, onStateChange }: Omit<ChatUiProps, 'spec'> & { spec: Spec }) {
+ const patches = useMemo(() => specToPatches(spec), [spec]);
+ const total = Math.max(0, patches.length - HEAD);
+ const count = useForwardReveal(total, live);
+ const shown = useMemo(() => (count >= total ? spec : specFromPatches(patches, HEAD + count)), [count, total, spec, patches]);
+
+ const latest = useRef({ actions, onStateChange });
+ useLayoutEffect(() => {
+ latest.current = { actions, onStateChange };
+ });
+ const [store] = useState(() =>
+ createUiStateStore(state ?? spec.state ?? {}, (changes) => latest.current.onStateChange?.(changes)),
+ );
+ const [handlers] = useState(() => chatActionHandlers(partId, () => latest.current.actions));
+
+ return (
+ <LiveUiContext.Provider value={live}>
+ <JSONUIProvider registry={chatRegistry} store={store} handlers={handlers}>
+ <Renderer spec={shown} registry={chatRegistry} loading={count < total} fallback={NoElement} />
+ </JSONUIProvider>
+ </LiveUiContext.Provider>
+ );
+}
+
+export default function ChatUi(props: ChatUiProps) {
+ const spec = useMemo(() => prepareChatSpec(props.spec), [props.spec]);
+ // Nothing until the root has arrived: by then its state has too.
+ if (!spec) return null;
+ return <ChatUiBody {...props} spec={spec} />;
+}
diff --git a/client/src/features/chat/genui/actions.ts b/client/src/features/chat/genui/actions.ts
new file mode 100644
index 00000000..b2cbc645
--- /dev/null
+++ b/client/src/features/chat/genui/actions.ts
@@ -0,0 +1,72 @@
+/**
+ * What a reply's buttons do, as json-render action handlers. json-render
+ * runs `setState` itself; every other action reaches these with its params
+ * resolved against the UI's state at the press (and the press's tags,
+ * genui/prepare.ts):
+ *
+ * - `ask` with the text the button would send. The chat sends it as the
+ * owner's message only when it is exactly what the button says; otherwise
+ * the text goes into the message box for the owner to read first
+ * (`ChatUiActions.ask` decides).
+ * - Any other name goes back to the employee as a button press
+ * (`ChatUiActions.event`), the UI, element, action and params named.
+ *
+ * Action names are open-ended (the employee names its own), so the handlers
+ * are a Proxy that answers any usable name; json-render keeps the object it
+ * is given and looks names up on it.
+ */
+
+import { isUsableName } from '@/lib/jsonRender/sanitize';
+import { untagged } from './prepare';
+
+export interface ChatUiEvent {
+ partId: string;
+ elementId: string;
+ action: string;
+ params: Record<string, unknown>;
+ /** The pressed button's label, as it read at the press. */
+ label: string;
+}
+
+export interface ChatUiActions {
+ ask: (text: string, label: string) => void;
+ event: (event: ChatUiEvent) => void;
+}
+
+/** Names json-render handles itself, and names no handler object should
+ * answer (a Proxy that answered `then` would look like a promise). */
+const NOT_HANDLED = new Set(['setState', 'pushState', 'removeState', 'push', 'pop', 'validateForm', 'then', 'toJSON']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The handlers for one UI. `actions` is read at each press, so the
+ * handlers can be made once per UI while the chat's callbacks change. */
+export function chatActionHandlers(
+ partId: string,
+ actions: () => ChatUiActions,
+): Record<string, (params: Record<string, unknown>) => void> {
+ const handle = (action: string) => (raw: Record<string, unknown>) => {
+ const press = untagged(isRecord(raw) ? raw : {});
+ if (action === 'ask') {
+ const text = typeof press.params.text === 'string' ? press.params.text.trim() : '';
+ if (text) actions().ask(text, press.label);
+ return;
+ }
+ actions().event({ partId, elementId: press.elementId, action, params: press.params, label: press.label });
+ };
+ return new Proxy(Object.create(null) as Record<string, (params: Record<string, unknown>) => void>, {
+ get(_target, name) {
+ if (typeof name !== 'string' || NOT_HANDLED.has(name) || !isUsableName(name)) return undefined;
+ if (name in Object.prototype) return undefined;
+ return handle(name);
+ },
+ });
+}
+
+/** Whether `ask`'s text is what its button says, so it can go at once. */
+export function asksWhatItSays(text: string, label: string): boolean {
+ const norm = (value: string) => value.replace(/\s+/g, ' ').trim().toLowerCase();
+ return norm(text).length > 0 && norm(text) === norm(label);
+}
diff --git a/client/src/features/chat/genui/catalog.ts b/client/src/features/chat/genui/catalog.ts
new file mode 100644
index 00000000..45705acc
--- /dev/null
+++ b/client/src/features/chat/genui/catalog.ts
@@ -0,0 +1,192 @@
+/**
+ * What an employee may show inside a chat reply (design handoff chat,
+ * "Generated UI"): the components, what they hold, which prop a control
+ * binds, and the limits. The server checks a spec against
+ * server/config/chat_genui_catalog.json before anything shows; this file is
+ * the client's side of the same vocabulary, and a test reads that manifest
+ * off disk and checks the two agree (keep the lists below plain literals).
+ *
+ * Prop schemas are forgiving by design: an odd value degrades that one prop
+ * (a default, a clamped string) instead of failing the element.
+ */
+
+import { z } from 'zod';
+
+export const CHAT_COMPONENT_TYPES = [
+ 'Stack',
+ 'Row',
+ 'Card',
+ 'SlotPicker',
+ 'Select',
+ 'Toggle',
+ 'TextField',
+ 'Text',
+ 'StatGrid',
+ 'BarChart',
+ 'Callout',
+ 'Button',
+] as const;
+export type ChatComponentType = (typeof CHAT_COMPONENT_TYPES)[number];
+
+export type ComponentRole = 'layout' | 'input' | 'display' | 'action';
+
+export const COMPONENT_ROLES = {
+ Stack: 'layout',
+ Row: 'layout',
+ Card: 'layout',
+ SlotPicker: 'input',
+ Select: 'input',
+ Toggle: 'input',
+ TextField: 'input',
+ Text: 'display',
+ StatGrid: 'display',
+ BarChart: 'display',
+ Callout: 'display',
+ Button: 'action',
+} as const satisfies Record<ChatComponentType, ComponentRole>;
+
+/** What a layout may hold: any component, or only these. */
+export const COMPONENT_CHILDREN = {
+ Stack: 'any',
+ Row: ['Button'],
+ Card: ['Select', 'Toggle', 'TextField', 'Text'],
+} as const satisfies Partial<Record<ChatComponentType, 'any' | readonly ChatComponentType[]>>;
+
+/** The prop each control reads and writes through `{"$bindState": "/path"}`. */
+export const BIND_PROPS = {
+ SlotPicker: 'value',
+ Select: 'value',
+ Toggle: 'checked',
+ TextField: 'value',
+} as const satisfies Partial<Record<ChatComponentType, string>>;
+
+export const COMPONENT_EVENTS = {
+ Button: ['press'],
+} as const satisfies Partial<Record<ChatComponentType, readonly string[]>>;
+
+/** Actions the chat runs itself; any other comes back to the employee. */
+export const CHAT_ACTIONS = ['ask', 'setState'] as const;
+
+export const CHAT_LIMITS = {
+ maxElements: 24,
+ maxDepth: 6,
+ maxBytes: 16384,
+ maxChildren: 12,
+ maxIdLength: 40,
+ maxPathSegments: 6,
+} as const;
+
+// ----- prop schemas (resolved values) -----
+
+function clamp(value: string, max: number): string {
+ const flat = value.replace(/\s+/g, ' ').trim();
+ return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+
+const scalar = z.union([z.string(), z.number(), z.boolean()]).transform(String);
+/** A one-line string, whitespace collapsed and clamped; '' when unusable. */
+const line = (max: number) => scalar.catch('').transform((s) => clamp(s, max));
+const optionalLine = (max: number) => line(max).optional().catch(undefined);
+const flag = z.boolean().optional().catch(undefined);
+const gap = z.enum(['sm', 'md']).catch('md');
+
+function listOf<T extends z.ZodType>(item: T, max: number) {
+ return z
+ .array(z.unknown())
+ .catch([])
+ .transform((items) =>
+ items
+ .map((raw) => item.safeParse(raw))
+ .filter((result) => result.success)
+ .map((result) => result.data as z.output<T>)
+ .slice(0, max),
+ );
+}
+
+const slotOption = z.object({
+ id: line(40),
+ time: line(40),
+ detail: optionalLine(60),
+ recommended: flag,
+ unavailable: flag,
+ note: optionalLine(80),
+});
+
+const stat = z.object({
+ label: line(40),
+ value: line(40),
+ delta: optionalLine(40),
+ tone: z.enum(['up', 'down']).optional().catch(undefined),
+});
+
+const bar = z.object({
+ label: line(40),
+ value: z.coerce
+ .number()
+ .catch(0)
+ .transform((value) => (Number.isFinite(value) && value > 0 ? value : 0)),
+});
+
+export const CHAT_PROP_SCHEMAS = {
+ Stack: z.object({ gap }),
+ Row: z.object({ gap }),
+ Card: z.object({ title: line(80), description: optionalLine(240) }),
+ SlotPicker: z.object({
+ label: line(80),
+ hint: optionalLine(120),
+ value: optionalLine(40),
+ options: listOf(slotOption, 8).transform((options) => options.filter((option) => option.id && option.time)),
+ }),
+ Select: z.object({
+ label: line(80),
+ value: optionalLine(40),
+ options: listOf(line(40), 6).transform((options) => [...new Set(options.filter(Boolean))]),
+ }),
+ Toggle: z.object({ label: line(80), hint: optionalLine(120), checked: z.boolean().catch(false) }),
+ TextField: z.object({
+ label: line(80),
+ placeholder: optionalLine(80),
+ value: scalar.catch('').transform((s) => s.slice(0, 400)),
+ }),
+ Text: z.object({ text: scalar.catch('').transform((s) => s.trim().slice(0, 600)) }),
+ StatGrid: z.object({ items: listOf(stat, 6).transform((items) => items.filter((item) => item.label)) }),
+ BarChart: z.object({ title: line(80), bars: listOf(bar, 12).transform((bars) => bars.filter((item) => item.label)) }),
+ Callout: z.object({ tone: z.enum(['info', 'warning', 'danger', 'success']).catch('info'), text: line(400) }),
+ Button: z.object({ label: line(40), variant: z.enum(['primary', 'secondary']).catch('secondary') }),
+} satisfies Record<ChatComponentType, z.ZodType>;
+
+export type ChatPropsOf<T extends ChatComponentType> = z.output<(typeof CHAT_PROP_SCHEMAS)[T]>;
+
+export function isChatComponentType(value: unknown): value is ChatComponentType {
+ return typeof value === 'string' && (CHAT_COMPONENT_TYPES as readonly string[]).includes(value);
+}
+
+/** The parents each component may sit under (null: the root), from what
+ * each layout may hold. */
+export function allowedParents(type: ChatComponentType): (ChatComponentType | null)[] {
+ const parents: (ChatComponentType | null)[] = [null];
+ for (const [layout, children] of Object.entries(COMPONENT_CHILDREN) as [ChatComponentType, 'any' | readonly ChatComponentType[]][]) {
+ if (children === 'any' || children.includes(type)) parents.push(layout);
+ }
+ return parents;
+}
+
+// ----- the catalogue as json-render takes it -----
+
+type ChatCatalogComponents = {
+ [T in ChatComponentType]: { props: (typeof CHAT_PROP_SCHEMAS)[T]; slots?: string[] };
+};
+
+function catalogComponents(): ChatCatalogComponents {
+ const components: Partial<Record<ChatComponentType, { props: z.ZodType; slots?: string[] }>> = {};
+ for (const type of CHAT_COMPONENT_TYPES) {
+ const props = CHAT_PROP_SCHEMAS[type];
+ components[type] = type in COMPONENT_CHILDREN ? { props, slots: ['default'] } : { props };
+ }
+ return components as ChatCatalogComponents;
+}
+
+/** What json-render's defineCatalog takes for a chat reply's UI. The
+ * handlers come from the chat when it renders (any action name is
+ * routed: genui/actions.ts); setState is json-render's own. */
+export const CHAT_CATALOG = { components: catalogComponents(), actions: {} };
diff --git a/client/src/features/chat/genui/prepare.ts b/client/src/features/chat/genui/prepare.ts
new file mode 100644
index 00000000..e369986a
--- /dev/null
+++ b/client/src/features/chat/genui/prepare.ts
@@ -0,0 +1,78 @@
+/**
+ * A generated UI made ready for json-render. The server checked the spec
+ * already (server/services/genui/spec.py); this side sanitizes it again
+ * (lib/jsonRender/sanitize.ts, with the chat's limits), leaves out
+ * components the chat catalogue does not have, and tags each Button's press
+ * with the element and its label (`PRESS_ELEMENT`, `PRESS_LABEL`), because
+ * json-render hands an action handler the resolved params only: the `ask`
+ * action needs the label to tell whether its text is what the button says,
+ * and any other action is sent back to the employee naming the element.
+ *
+ * Pure, and free of json-render at run time.
+ */
+
+import type { ActionBinding, Spec, UIElement } from '@json-render/core';
+import { DEFAULT_SANITIZE_LIMITS, sanitizeSpec, type SanitizeLimits } from '@/lib/jsonRender/sanitize';
+import { CHAT_LIMITS, isChatComponentType } from './catalog';
+
+/** The keys a pressed button adds to its action's params. */
+export const PRESS_ELEMENT = '__oc_element';
+export const PRESS_LABEL = '__oc_label';
+
+export const CHAT_SANITIZE_LIMITS: SanitizeLimits = {
+ ...DEFAULT_SANITIZE_LIMITS,
+ maxElements: CHAT_LIMITS.maxElements,
+ maxChildren: CHAT_LIMITS.maxChildren,
+ maxIdLength: CHAT_LIMITS.maxIdLength,
+ maxPathSegments: CHAT_LIMITS.maxPathSegments,
+};
+
+function tagged(binding: ActionBinding, id: string, label: unknown): ActionBinding {
+ return { ...binding, params: { ...(binding.params ?? {}), [PRESS_ELEMENT]: id, [PRESS_LABEL]: label ?? '' } };
+}
+
+function withPressIdentity(id: string, element: UIElement): UIElement {
+ const press = element.on?.press;
+ if (element.type !== 'Button' || !press) return element;
+ const label = element.props.label;
+ const bindings = Array.isArray(press) ? press.map((binding) => tagged(binding, id, label)) : tagged(press, id, label);
+ return { ...element, on: { ...element.on, press: bindings } };
+}
+
+/**
+ * The spec to render, or null while it has no root element (a UI still
+ * arriving starts empty). Children that name a dropped component are
+ * removed; children not here yet stay (they may still be on their way).
+ */
+export function prepareChatSpec(raw: unknown): Spec | null {
+ const spec = sanitizeSpec(raw, CHAT_SANITIZE_LIMITS);
+ if (!spec) return null;
+ const dropped = new Set<string>();
+ const kept: Record<string, UIElement> = Object.create(null);
+ for (const [id, element] of Object.entries(spec.elements)) {
+ if (isChatComponentType(element.type)) kept[id] = element;
+ else dropped.add(id);
+ }
+ if (!Object.prototype.hasOwnProperty.call(kept, spec.root)) return null;
+ const elements: Record<string, UIElement> = Object.create(null);
+ for (const [id, element] of Object.entries(kept)) {
+ const children = element.children?.filter((child) => !dropped.has(child));
+ const clean = children && children.length !== element.children?.length ? { ...element, children } : element;
+ elements[id] = withPressIdentity(id, clean);
+ }
+ return { root: spec.root, state: spec.state, elements };
+}
+
+/** A press's params as the employee should see them: without the tags. */
+export function untagged(params: Record<string, unknown>): {
+ elementId: string;
+ label: string;
+ params: Record<string, unknown>;
+} {
+ const { [PRESS_ELEMENT]: element, [PRESS_LABEL]: label, ...rest } = params;
+ return {
+ elementId: typeof element === 'string' ? element : '',
+ label: typeof label === 'string' ? label : label === undefined || label === null ? '' : String(label),
+ params: rest,
+ };
+}
diff --git a/client/src/features/chat/genui/registry.ts b/client/src/features/chat/genui/registry.ts
new file mode 100644
index 00000000..a692e3bd
--- /dev/null
+++ b/client/src/features/chat/genui/registry.ts
@@ -0,0 +1,48 @@
+/**
+ * The chat's generated UI for json-render: the catalogue (catalog.ts's
+ * CHAT_CATALOG) and its registry, a guarded component for each of the
+ * twelve types (views.tsx drawn through lib/jsonRender/guard.tsx, which reads
+ * each element's props through the catalogue's forgiving schema first and
+ * holds it to the parents it may appear under).
+ *
+ * Defined here, not in catalog.ts, because this module loads only with a
+ * generated UI (ChatUi), and json-render with it.
+ */
+
+import { defineCatalog } from '@json-render/core';
+import { defineRegistry, schema } from '@json-render/react';
+import { guarded } from '@/lib/jsonRender';
+import { CHAT_CATALOG, CHAT_PROP_SCHEMAS, allowedParents } from './catalog';
+import {
+ BarChartView,
+ ButtonView,
+ CalloutView,
+ CardView,
+ RowView,
+ SelectView,
+ SlotPickerView,
+ StackView,
+ StatGridView,
+ TextFieldView,
+ TextView,
+ ToggleView,
+} from './views';
+
+export const chatCatalog = defineCatalog(schema, CHAT_CATALOG);
+
+export const { registry: chatRegistry } = defineRegistry(chatCatalog, {
+ components: {
+ Stack: guarded('Stack', CHAT_PROP_SCHEMAS.Stack, StackView, { parents: allowedParents('Stack') }),
+ Row: guarded('Row', CHAT_PROP_SCHEMAS.Row, RowView, { parents: allowedParents('Row') }),
+ Card: guarded('Card', CHAT_PROP_SCHEMAS.Card, CardView, { parents: allowedParents('Card') }),
+ SlotPicker: guarded('SlotPicker', CHAT_PROP_SCHEMAS.SlotPicker, SlotPickerView, { parents: allowedParents('SlotPicker') }),
+ Select: guarded('Select', CHAT_PROP_SCHEMAS.Select, SelectView, { parents: allowedParents('Select') }),
+ Toggle: guarded('Toggle', CHAT_PROP_SCHEMAS.Toggle, ToggleView, { parents: allowedParents('Toggle') }),
+ TextField: guarded('TextField', CHAT_PROP_SCHEMAS.TextField, TextFieldView, { parents: allowedParents('TextField') }),
+ Text: guarded('Text', CHAT_PROP_SCHEMAS.Text, TextView, { parents: allowedParents('Text') }),
+ StatGrid: guarded('StatGrid', CHAT_PROP_SCHEMAS.StatGrid, StatGridView, { parents: allowedParents('StatGrid') }),
+ BarChart: guarded('BarChart', CHAT_PROP_SCHEMAS.BarChart, BarChartView, { parents: allowedParents('BarChart') }),
+ Callout: guarded('Callout', CHAT_PROP_SCHEMAS.Callout, CalloutView, { parents: allowedParents('Callout') }),
+ Button: guarded('Button', CHAT_PROP_SCHEMAS.Button, ButtonView, { parents: allowedParents('Button') }),
+ },
+});
diff --git a/client/src/features/chat/genui/views.tsx b/client/src/features/chat/genui/views.tsx
new file mode 100644
index 00000000..9c6677aa
--- /dev/null
+++ b/client/src/features/chat/genui/views.tsx
@@ -0,0 +1,267 @@
+/**
+ * The twelve components an employee can show in a chat reply (design
+ * handoff chat, catalog.json), as json-render draws them. registry.ts wraps
+ * each in the guard (lib/jsonRender/guard.tsx), which reads the element's
+ * props through the catalogue's forgiving schema first, so these get props
+ * already parsed, plus the ref that plays their entrance.
+ *
+ * Controls write through json-render's bindings: SlotPicker's, Select's and
+ * TextField's `value`, Toggle's `checked`. A Button presses its `on.press`
+ * binding (emit), which json-render resolves against the UI's state and
+ * hands to the chat's action handlers (genui/actions.ts).
+ *
+ * Surfaces follow the handoff's token map: panels on `--bg-panel` with the
+ * default border, the picked option in the tools tint, a primary button in
+ * the run tint, a callout's tone in the save / config / stop / run tints.
+ */
+
+import { useBoundProp } from '@json-render/react';
+import { Check, CircleAlert, Info, TriangleAlert } from 'lucide-react';
+import { ActionButton } from '@/components/ui/action-button';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Switch } from '@/components/ui/switch';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import type { GuardedComponentProps } from '@/lib/jsonRender';
+import { cn } from '@/lib/utils';
+import type { ChatComponentType, ChatPropsOf } from './catalog';
+
+type ViewProps<T extends ChatComponentType> = GuardedComponentProps<ChatPropsOf<T>>;
+
+const GAP = { sm: 'gap-2', md: 'gap-3' } as const;
+
+const CALLOUT = {
+ info: { surface: 'border-action-save-border bg-action-save-soft', ink: 'text-action-save-ink', Icon: Info },
+ warning: { surface: 'border-action-config-border bg-action-config-soft', ink: 'text-action-config-ink', Icon: TriangleAlert },
+ danger: { surface: 'border-action-stop-border bg-action-stop-soft', ink: 'text-action-stop-ink', Icon: CircleAlert },
+ success: { surface: 'border-action-run-border bg-action-run-soft', ink: 'text-action-run-ink', Icon: Check },
+} as const;
+
+const PANEL = 'rounded-xl border border-border-default bg-bg-panel';
+
+// ----- layout -----
+
+export function StackView({ props, children, enterRef }: ViewProps<'Stack'>) {
+ return (
+ <div ref={enterRef} className={cn('flex min-w-0 flex-col', GAP[props.gap])}>
+ {children}
+ </div>
+ );
+}
+
+export function RowView({ props, children, enterRef }: ViewProps<'Row'>) {
+ return (
+ <div ref={enterRef} className={cn('flex min-w-0 flex-wrap items-center', GAP[props.gap])}>
+ {children}
+ </div>
+ );
+}
+
+export function CardView({ props, children, enterRef }: ViewProps<'Card'>) {
+ return (
+ <section ref={enterRef} aria-label={props.title || undefined} className={cn(PANEL, 'flex min-w-0 flex-col gap-3.5 px-4 py-3.5')}>
+ {(props.title || props.description) && (
+ <header className="flex flex-col gap-0.5">
+ {props.title && <h3 className="m-0 text-sm font-semibold text-fg-default">{props.title}</h3>}
+ {props.description && <p className="m-0 text-xs text-fg-muted">{props.description}</p>}
+ </header>
+ )}
+ {children}
+ </section>
+ );
+}
+
+// ----- inputs -----
+
+export function SlotPickerView({ props, bindings, enterRef }: ViewProps<'SlotPicker'>) {
+ const [, setValue] = useBoundProp<string>(props.value, bindings?.value);
+ if (props.options.length === 0) return null;
+ return (
+ <div ref={enterRef} role="radiogroup" aria-label={props.label} className="flex min-w-0 flex-col gap-2">
+ <div className="flex flex-wrap items-baseline gap-x-2">
+ <span className="text-sm font-semibold text-fg-default">{props.label}</span>
+ {props.hint && <span className="text-xs text-fg-muted">{props.hint}</span>}
+ </div>
+ <div className="grid grid-cols-[repeat(auto-fill,minmax(7.5rem,1fr))] gap-2">
+ {props.options.map((option) => {
+ const picked = option.id === props.value;
+ return (
+ <button
+ key={option.id}
+ type="button"
+ role="radio"
+ aria-checked={picked}
+ disabled={option.unavailable}
+ onClick={() => setValue(option.id)}
+ className={cn(
+ 'relative flex min-w-0 flex-col items-start gap-0.5 rounded-xl border px-3 py-2.5 text-left transition-colors duration-(--dur-default)',
+ picked
+ ? 'border-action-tools-border bg-action-tools-soft text-action-tools-ink'
+ : 'border-border-default bg-bg-panel text-fg-default hover:border-border-strong hover:bg-bg-hover',
+ option.unavailable && 'cursor-not-allowed opacity-55 hover:border-border-default hover:bg-bg-panel',
+ )}
+ >
+ <span className="font-mono text-sm font-semibold">{option.time}</span>
+ {option.detail && <span className={cn('text-xs', picked ? 'text-action-tools-ink' : 'text-fg-muted')}>{option.detail}</span>}
+ {option.note && <span className="text-2xs text-fg-faint">{option.note}</span>}
+ {option.recommended && !option.unavailable && (
+ <span className="absolute top-2 right-2 rounded-pill border border-action-run-border bg-action-run-soft px-1.5 font-mono text-2xs text-action-run-ink">
+ Best
+ </span>
+ )}
+ </button>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
+
+export function SelectView({ props, bindings, enterRef }: ViewProps<'Select'>) {
+ const [, setValue] = useBoundProp<string>(props.value, bindings?.value);
+ if (props.options.length === 0) return null;
+ return (
+ <div ref={enterRef} className="flex min-w-0 flex-col gap-1.5">
+ <span className="text-xs font-medium text-fg-muted">{props.label}</span>
+ <ToggleGroup
+ type="single"
+ variant="chips"
+ aria-label={props.label}
+ value={props.value ?? ''}
+ onValueChange={(next) => next && setValue(next)}
+ className="self-start"
+ >
+ {props.options.map((option) => (
+ <ToggleGroupItem key={option} value={option}>
+ {option}
+ </ToggleGroupItem>
+ ))}
+ </ToggleGroup>
+ </div>
+ );
+}
+
+export function ToggleView({ props, bindings, enterRef }: ViewProps<'Toggle'>) {
+ const [, setChecked] = useBoundProp<boolean>(props.checked, bindings?.checked);
+ return (
+ <div ref={enterRef} className="flex items-center gap-3">
+ <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+ <span className="text-sm font-medium text-fg-default">{props.label}</span>
+ {props.hint && <span className="text-xs text-fg-muted">{props.hint}</span>}
+ </div>
+ <Switch tone="run" aria-label={props.label} checked={props.checked} onCheckedChange={setChecked} />
+ </div>
+ );
+}
+
+export function TextFieldView({ props, bindings, enterRef }: ViewProps<'TextField'>) {
+ const [, setValue] = useBoundProp<string>(props.value, bindings?.value);
+ return (
+ <label ref={enterRef} className="flex min-w-0 flex-col gap-1.5 text-xs font-medium text-fg-muted">
+ {props.label}
+ <Input
+ value={props.value}
+ placeholder={props.placeholder}
+ maxLength={400}
+ disabled={!bindings?.value}
+ onChange={(event) => setValue(event.target.value)}
+ className="h-9 rounded-lg bg-bg-input px-3 text-sm font-normal text-fg-default"
+ />
+ </label>
+ );
+}
+
+// ----- display -----
+
+export function TextView({ props, enterRef }: ViewProps<'Text'>) {
+ if (!props.text) return null;
+ return (
+ <p ref={enterRef} className="m-0 text-sm leading-relaxed text-fg-muted">
+ {props.text}
+ </p>
+ );
+}
+
+export function StatGridView({ props, enterRef }: ViewProps<'StatGrid'>) {
+ if (props.items.length === 0) return null;
+ return (
+ <div ref={enterRef} className="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-2">
+ {props.items.map((item, index) => (
+ <div key={`${item.label}-${index}`} className={cn(PANEL, 'flex min-w-0 flex-col gap-1 px-3.5 py-3')}>
+ <span className="font-mono text-2xs tracking-label text-fg-faint uppercase">{item.label}</span>
+ <span className="text-xl font-semibold tracking-hero text-fg-default tabular-nums">{item.value}</span>
+ {item.delta && (
+ <span
+ className={cn(
+ 'text-xs font-medium',
+ item.tone === 'up' ? 'text-action-run-ink' : item.tone === 'down' ? 'text-action-stop-ink' : 'text-fg-muted',
+ )}
+ >
+ {item.delta}
+ </span>
+ )}
+ </div>
+ ))}
+ </div>
+ );
+}
+
+export function BarChartView({ props, enterRef }: ViewProps<'BarChart'>) {
+ if (props.bars.length === 0) return null;
+ const most = Math.max(...props.bars.map((item) => item.value), 0);
+ return (
+ <figure ref={enterRef} className={cn(PANEL, 'm-0 flex min-w-0 flex-col gap-2.5 px-4 py-3.5')}>
+ {props.title && <figcaption className="text-sm font-semibold text-fg-default">{props.title}</figcaption>}
+ <ul className="m-0 flex list-none flex-col gap-2.5 p-0">
+ {props.bars.map((item, index) => (
+ <li key={`${item.label}-${index}`} className="grid grid-cols-[minmax(0,9rem)_minmax(0,1fr)_2.5rem] items-center gap-2.5">
+ <span className="truncate text-xs text-fg-muted">{item.label}</span>
+ <span className="h-2 overflow-hidden rounded-pill bg-bg-active">
+ <span
+ className="opencompany-grow block h-full rounded-[inherit] bg-action-tools-ink"
+ // The bar's length is the value itself.
+ style={{ width: `${most > 0 ? (item.value / most) * 100 : 0}%`, animationDelay: `${index * 60}ms` }}
+ />
+ </span>
+ <span className="text-right font-mono text-xs font-medium text-fg-default">{item.value}</span>
+ </li>
+ ))}
+ </ul>
+ </figure>
+ );
+}
+
+export function CalloutView({ props, enterRef }: ViewProps<'Callout'>) {
+ if (!props.text) return null;
+ const tone = CALLOUT[props.tone];
+ return (
+ <div ref={enterRef} role="note" className={cn('flex gap-2.5 rounded-xl border px-3.5 py-3 text-sm leading-normal', tone.surface)}>
+ <tone.Icon aria-hidden className={cn('mt-0.5 size-3.75 shrink-0', tone.ink)} strokeWidth={2} />
+ <span className="text-fg-default">{props.text}</span>
+ </div>
+ );
+}
+
+// ----- actions -----
+
+export function ButtonView({ props, emit, enterRef }: ViewProps<'Button'>) {
+ if (!props.label) return null;
+ const press = () => emit('press');
+ if (props.variant === 'primary') {
+ return (
+ <ActionButton ref={enterRef} intent="run" onClick={press} className="h-8.5 rounded-lg px-3.5 whitespace-nowrap active:translate-y-px">
+ {props.label}
+ </ActionButton>
+ );
+ }
+ return (
+ <Button
+ ref={enterRef}
+ variant="quiet"
+ onClick={press}
+ className="h-8.5 rounded-lg border-border-default px-3.5 font-semibold text-fg-default hover:bg-bg-hover"
+ >
+ {props.label}
+ </Button>
+ );
+}
diff --git a/client/src/features/chat/markdown/CitationChip.tsx b/client/src/features/chat/markdown/CitationChip.tsx
new file mode 100644
index 00000000..08849b24
--- /dev/null
+++ b/client/src/features/chat/markdown/CitationChip.tsx
@@ -0,0 +1,52 @@
+/**
+ * A citation in an answer's text (design handoff chat, "[n] source chips"):
+ * a small numbered chip in the save tint, numbered as the reply numbers its
+ * sources. It names the source on hover and focus, and opens it in a new
+ * tab when the source has an address.
+ */
+
+import { useContext } from 'react';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { CitationContext } from './citationContext';
+
+const CHIP =
+ 'mx-0.5 inline-grid h-4.25 min-w-4.25 place-items-center rounded-pill bg-action-save-soft px-1 align-[2px] font-mono text-2xs font-semibold text-action-save-ink no-underline';
+
+function hostOf(url: string | null): string | null {
+ if (!url) return null;
+ try {
+ return new URL(url).hostname.replace(/^www\./, '');
+ } catch {
+ return null;
+ }
+}
+
+export function CitationChip({ n }: { n: number }) {
+ const { order, sources } = useContext(CitationContext);
+ const shown = order.get(n);
+ const source = sources.get(n);
+ if (shown === undefined || !source) return <>[{n}]</>;
+ const host = hostOf(source.url);
+ const label = `Source ${shown}: ${source.title}${host ? ` (${host})` : ''}`;
+ const chip = source.url ? (
+ <a href={source.url} target="_blank" rel="noopener noreferrer" aria-label={label} className={CHIP}>
+ {shown}
+ </a>
+ ) : (
+ <span role="note" aria-label={label} tabIndex={0} className={CHIP}>
+ {shown}
+ </span>
+ );
+ // Its own provider: the chat also renders outside the app shell's.
+ return (
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>{chip}</TooltipTrigger>
+ <TooltipContent className="max-w-72">
+ <span className="font-medium">{source.title}</span>
+ {host && <span className="block text-fg-muted">{host}</span>}
+ </TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ );
+}
diff --git a/client/src/features/chat/markdown/ReplyMarkdown.tsx b/client/src/features/chat/markdown/ReplyMarkdown.tsx
index 68ba0f61..b256452a 100644
--- a/client/src/features/chat/markdown/ReplyMarkdown.tsx
+++ b/client/src/features/chat/markdown/ReplyMarkdown.tsx
@@ -18,12 +18,14 @@ import 'prismjs/components/prism-markdown';
import 'prismjs/components/prism-python';
import 'prismjs/components/prism-typescript';
import 'prismjs/components/prism-yaml';
-import { memo, useMemo } from 'react';
+import { memo, useContext, useMemo } from 'react';
import ReactMarkdown, { type Components } from 'react-markdown';
import remarkBreaks from 'remark-breaks';
import remarkGfm from 'remark-gfm';
import { cn } from '@/lib/utils';
import { markdownBlocks } from './blocks';
+import { CitationContext } from './citationContext';
+import { linkCitations } from './citations';
import { CHAT_MARKDOWN_COMPONENTS } from './components';
const REMARK_PLUGINS = [remarkGfm, remarkBreaks];
@@ -74,7 +76,10 @@ const Block = memo(function Block({ text }: { text: string }) {
});
export default function ReplyMarkdown({ text, streaming = false, className }: { text: string; streaming?: boolean; className?: string }) {
- const blocks = useMemo(() => (streaming ? markdownBlocks(text) : [text]), [text, streaming]);
+ // Each [n] of a source the reply has becomes a citation chip.
+ const { sources } = useContext(CitationContext);
+ const linked = useMemo(() => linkCitations(text, new Set(sources.keys())), [text, sources]);
+ const blocks = useMemo(() => (streaming ? markdownBlocks(linked) : [linked]), [linked, streaming]);
return (
<div className={cn('chat-markdown min-w-0', className)} data-streaming={streaming || undefined}>
{blocks.map((block, index) => (
diff --git a/client/src/features/chat/markdown/citationContext.ts b/client/src/features/chat/markdown/citationContext.ts
new file mode 100644
index 00000000..79c2539e
--- /dev/null
+++ b/client/src/features/chat/markdown/citationContext.ts
@@ -0,0 +1,19 @@
+/**
+ * The sources a reply's text may cite, for ReplyMarkdown's citation chips:
+ * each cited source number with its display number in this reply, and the
+ * source itself. Set by the reply turn; empty where nothing is cited.
+ */
+
+import { createContext } from 'react';
+import type { SourceItem } from '../data/parts';
+
+export interface CitationInfo {
+ /** Source number -> display number in this reply (1, 2, ...). */
+ order: ReadonlyMap<number, number>;
+ /** Source number -> source. */
+ sources: ReadonlyMap<number, SourceItem>;
+}
+
+export const NO_CITATIONS: CitationInfo = { order: new Map(), sources: new Map() };
+
+export const CitationContext = createContext<CitationInfo>(NO_CITATIONS);
diff --git a/client/src/features/chat/markdown/citations.ts b/client/src/features/chat/markdown/citations.ts
new file mode 100644
index 00000000..037c3e3f
--- /dev/null
+++ b/client/src/features/chat/markdown/citations.ts
@@ -0,0 +1,65 @@
+/**
+ * Citations in an answer (docs-internal/chat_protocol.md, "Sources"): the
+ * employee cites a source it was given as `[n]`, n being the source's number
+ * in the conversation. A reply shows its sources numbered 1, 2, ... in the
+ * order it first cites them, so `[7]` in the text reads as the chip "1".
+ *
+ * `citationOrder` says which display number each cited source gets;
+ * `linkCitations` turns each `[n]` of a known source into a markdown link
+ * (`#cite-<n>`) that ReplyMarkdown draws as a chip. Code (inline or fenced)
+ * is left as written.
+ */
+
+const CITATION = /\[(\d{1,4})\]/g;
+export const CITE_HREF_PREFIX = '#cite-';
+
+/** The text outside code: `[segment, isCode]` pairs in order. */
+function segments(text: string): [string, boolean][] {
+ const out: [string, boolean][] = [];
+ const pattern = /(```[\s\S]*?(?:```|$)|`[^`\n]*`)/g;
+ let last = 0;
+ for (const match of text.matchAll(pattern)) {
+ const start = match.index ?? 0;
+ if (start > last) out.push([text.slice(last, start), false]);
+ out.push([match[0], true]);
+ last = start + match[0].length;
+ }
+ if (last < text.length) out.push([text.slice(last), false]);
+ return out;
+}
+
+/** Each cited source number (of those in `known`) with its display number,
+ * in the order the text first cites them. */
+export function citationOrder(text: string, known: ReadonlySet<number>): Map<number, number> {
+ const order = new Map<number, number>();
+ for (const [segment, code] of segments(text)) {
+ if (code) continue;
+ for (const match of segment.matchAll(CITATION)) {
+ const n = Number(match[1]);
+ if (known.has(n) && !order.has(n)) order.set(n, order.size + 1);
+ }
+ }
+ return order;
+}
+
+/** The text with each `[n]` of a known source made a `#cite-n` link. A
+ * `[n]` already followed by `(` (a markdown link) is left alone. */
+export function linkCitations(text: string, known: ReadonlySet<number>): string {
+ if (known.size === 0) return text;
+ return segments(text)
+ .map(([segment, code]) =>
+ code
+ ? segment
+ : segment.replace(CITATION, (whole, digits: string, offset: number, source: string) =>
+ known.has(Number(digits)) && source[offset + whole.length] !== '(' ? `[${digits}](${CITE_HREF_PREFIX}${digits})` : whole,
+ ),
+ )
+ .join('');
+}
+
+/** The source number a `#cite-n` link names, or null. */
+export function citedNumber(href: string | undefined): number | null {
+ if (!href?.startsWith(CITE_HREF_PREFIX)) return null;
+ const n = Number(href.slice(CITE_HREF_PREFIX.length));
+ return Number.isInteger(n) && n > 0 ? n : null;
+}
diff --git a/client/src/features/chat/markdown/components.tsx b/client/src/features/chat/markdown/components.tsx
index 27bc3c09..3a99f591 100644
--- a/client/src/features/chat/markdown/components.tsx
+++ b/client/src/features/chat/markdown/components.tsx
@@ -1,14 +1,21 @@
/**
* Element overrides for markdown in chat replies, shared by Home's thread and
* Dev's chat pane: links open in a new tab, so following one never leaves the
- * conversation, and images go through SafeImage.
+ * conversation; a citation link (`#cite-<n>`, markdown/citations.ts) is a
+ * citation chip; and images go through SafeImage.
*/
import type { Components } from 'react-markdown';
+import { CitationChip } from './CitationChip';
+import { citedNumber } from './citations';
import { SafeImage } from './SafeImage';
export const CHAT_MARKDOWN_COMPONENTS: Components = {
- a: ({ node: _node, ...props }) => <a {...props} target="_blank" rel="noopener noreferrer" />,
+ a: ({ node: _node, ...props }) => {
+ const cited = citedNumber(props.href);
+ if (cited !== null) return <CitationChip n={cited} />;
+ return <a {...props} target="_blank" rel="noopener noreferrer" />;
+ },
img: SafeImage,
};
diff --git a/client/src/features/chat/state/composerStore.ts b/client/src/features/chat/state/composerStore.ts
index cf85c1ed..387f43ed 100644
--- a/client/src/features/chat/state/composerStore.ts
+++ b/client/src/features/chat/state/composerStore.ts
@@ -33,7 +33,8 @@ interface ComposerState {
const EMPTY: ComposerDraft = { text: '', clientMessageId: null };
-function newClientMessageId(): string {
+/** A new `client_message_id` for a message sent from this tab. */
+export function newClientMessageId(): string {
return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
? crypto.randomUUID()
: `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
diff --git a/client/src/features/chat/thread/ChatThread.tsx b/client/src/features/chat/thread/ChatThread.tsx
index fed5df7e..54f3c666 100644
--- a/client/src/features/chat/thread/ChatThread.tsx
+++ b/client/src/features/chat/thread/ChatThread.tsx
@@ -17,8 +17,10 @@ import { useCallback, useLayoutEffect, useRef, useState, type ReactNode } from '
import { Button } from '@/components/ui/button';
import { Skeleton } from '@/components/ui/skeleton';
import { animate } from '@/lib/motion';
+import type { UiStateChange } from '@/lib/jsonRender/uiState';
import { prefersReducedMotion } from '@/lib/useReducedMotion';
import { cn } from '@/lib/utils';
+import type { ChatUiActions } from '../genui/actions';
import type { ChatPersona } from '../host';
import { AssistantTurn } from '../turns/AssistantTurn';
import { UserTurn } from '../turns/UserTurn';
@@ -52,6 +54,11 @@ export interface ChatThreadProps {
compact: boolean;
/** Esc stops a working run here, so its status line says so. */
canStop?: boolean;
+ /** What the buttons of an interface in a reply do. */
+ uiActions?: ChatUiActions;
+ onUiStateChange?: (partId: string, changes: UiStateChange[]) => void;
+ /** Sends a suggested next question as the owner's message. */
+ onFollowUp?: (text: string) => void;
onScrolledChange?: (scrolled: boolean) => void;
}
@@ -67,6 +74,9 @@ export function ChatThread({
liveNote,
compact,
canStop = false,
+ uiActions,
+ onUiStateChange,
+ onFollowUp,
onScrolledChange,
}: ChatThreadProps) {
const scrollRef = useRef<HTMLDivElement>(null);
@@ -196,12 +206,17 @@ export function ChatThread({
message={turn.message}
run={turn.run}
work={turn.work}
+ liveUi={turn.liveUi}
+ sources={turn.sources}
persona={persona}
now={now}
latest={latest}
compact={compact}
liveNote={liveNote}
canStop={canStop}
+ uiActions={uiActions}
+ onUiStateChange={onUiStateChange}
+ onFollowUp={onFollowUp}
/>
)}
</div>
diff --git a/client/src/features/chat/thread/model.ts b/client/src/features/chat/thread/model.ts
index 5f74ef87..1b0723cb 100644
--- a/client/src/features/chat/thread/model.ts
+++ b/client/src/features/chat/thread/model.ts
@@ -25,6 +25,7 @@
*/
import { emptyRun, isLiveRun, workedMs, type RunSnapshot, type RunStep } from '@/lib/agui/reduceRun';
+import { liveUiParts, savedSources, type SourceItem, type UiPart } from '../data/parts';
import type { ChatMessage, MessageRun } from '../data/schemas';
/** A run's working steps as its turn shows them. */
@@ -48,8 +49,16 @@ export type ChatTurn =
run: RunSnapshot | null;
/** The run's steps, on its first turn; null when it took none. */
work: TurnWork | null;
+ /** The interfaces the run streamed, on its first turn: shown until the
+ * saved reply carries them. */
+ liveUi: UiPart[];
+ /** The conversation's sources as of this answer, by number: its own and
+ * every earlier answer's, since an answer may cite an older one. */
+ sources: ReadonlyMap<number, SourceItem>;
};
+const NO_SOURCES: ReadonlyMap<number, SourceItem> = new Map();
+
/** Run failures that are not news: the conversation itself went away. */
const SILENT_FAILURES: ReadonlySet<string> = new Set(['reset', 'cleared']);
/** Failures that only say no answer came; an answer that landed after all
@@ -113,7 +122,7 @@ function shows(run: RunSnapshot, answered: boolean): boolean {
if (answered || run.result.noReply) return false;
return (
run.segments.some((segment) => segment.final !== false && segment.text.length > 0) ||
- (Boolean(run.result.replyMessageId) && run.steps.length > 0)
+ (Boolean(run.result.replyMessageId) && (run.steps.length > 0 || run.activities.length > 0))
);
}
@@ -141,6 +150,8 @@ export function buildTurns(messages: readonly ChatMessage[], runs: Readonly<Reco
const keyed = new Set<string>();
const turns: ChatTurn[] = [];
let generation: string | null = null;
+ // The conversation's sources so far; a new map only when an answer adds some.
+ let sources = NO_SOURCES;
visible.forEach((message, index) => {
if (generation && message.runKey && message.runKey !== generation) {
@@ -152,31 +163,43 @@ export function buildTurns(messages: readonly ChatMessage[], runs: Readonly<Reco
if (message.role === 'user') {
turns.push({ kind: 'user', key: `user:${message.clientMessageId ?? message.id}`, message });
if (runId && showing.has(runId) && !lastAnswer.has(runId) && lastIndex.get(runId) === index) {
- turns.push({ kind: 'assistant', key: `run:${runId}`, message: null, run: runs[runId], work: workOf(runs[runId]) });
+ const run = runs[runId];
+ turns.push({ kind: 'assistant', key: `run:${runId}`, message: null, run, work: workOf(run), liveUi: liveUiParts(run.activities), sources });
placed.add(runId);
keyed.add(runId);
}
return;
}
- // A run's first answer takes the key its own turn had, and its work.
+ // A run's first answer takes the key its own turn had, its work and
+ // what it streamed.
let key = `reply:${message.id}`;
let work: TurnWork | null = null;
+ let liveUi: UiPart[] = [];
if (runId && !keyed.has(runId)) {
key = `run:${runId}`;
work = workOf(runs[runId]);
+ liveUi = liveUiParts(runs[runId]?.activities);
keyed.add(runId);
}
const last = Boolean(runId && lastAnswer.get(runId) === index);
const run = runId && last && showing.has(runId) ? runs[runId] : null;
if (run) placed.add(run.runId);
- turns.push({ kind: 'assistant', key, message, run, work });
+ const own = savedSources(message.parts);
+ if (own.length > 0) {
+ const next = new Map(sources);
+ for (const source of own) next.set(source.n, source);
+ sources = next;
+ }
+ turns.push({ kind: 'assistant', key, message, run, work, liveUi, sources });
});
const unplaced = [...showing]
.map((runId) => runs[runId])
.filter((run) => !placed.has(run.runId) && isLiveRun(run))
.sort((a, b) => runOrder(a).localeCompare(runOrder(b)));
- for (const run of unplaced) turns.push({ kind: 'assistant', key: `run:${run.runId}`, message: null, run, work: workOf(run) });
+ for (const run of unplaced) {
+ turns.push({ kind: 'assistant', key: `run:${run.runId}`, message: null, run, work: workOf(run), liveUi: liveUiParts(run.activities), sources });
+ }
return turns;
}
diff --git a/client/src/features/chat/turns/AssistantTurn.tsx b/client/src/features/chat/turns/AssistantTurn.tsx
index 9f739c3e..a34c1f31 100644
--- a/client/src/features/chat/turns/AssistantTurn.tsx
+++ b/client/src/features/chat/turns/AssistantTurn.tsx
@@ -1,7 +1,8 @@
/**
* The employee's side of a turn (design handoff chat, "Assistant row"):
* their avatar on the left and, with no bubble, in order: what they did on
- * the way (the steps disclosure), and what they said in markdown.
+ * the way (the steps disclosure), what they said in markdown, and any
+ * interface they showed (GeneratedUiBlock).
*
* While their run works the avatar spins its ring; skeleton lines stand in
* for text that has not come yet; the answer streams in with a caret after
@@ -15,20 +16,30 @@
*/
import { CircleAlert, Pause, Square } from 'lucide-react';
-import { Suspense, lazy, type ReactNode } from 'react';
+import { Suspense, lazy, useMemo, type ReactNode } from 'react';
import { isLiveRun, type RunSnapshot } from '@/lib/agui/reduceRun';
+import type { UiStateChange } from '@/lib/jsonRender/uiState';
import { cn } from '@/lib/utils';
+import { savedFollowups, savedSources, savedUiParts, type SourceItem, type UiPart } from '../data/parts';
import type { ChatMessage } from '../data/schemas';
+import type { ChatUiActions } from '../genui/actions';
import type { ChatPersona } from '../host';
+import { CitationContext, NO_CITATIONS, type CitationInfo } from '../markdown/citationContext';
+import { citationOrder } from '../markdown/citations';
import { ChatAvatar } from '../thread/ChatAvatar';
import type { TurnWork } from '../thread/model';
import { timeLabel } from '../thread/timeLabel';
+import { GeneratedUiBlock } from './GeneratedUiBlock';
+import { FollowUps } from './FollowUps';
import { failureLines, liveLabel, liveText } from './runCopy';
+import { SourceChips } from './SourceChips';
import { StatusLine } from './StatusLine';
import { StepsDisclosure } from './StepsDisclosure';
import { TurnMeta } from './TurnMeta';
import { useWritingRate } from './useWritingRate';
+const NO_UI: UiPart[] = [];
+
// Its own chunk: the markdown stack stays out of the first load.
const ReplyMarkdown = lazy(() => import('../markdown/ReplyMarkdown'));
@@ -56,16 +67,26 @@ export function AssistantTurn({
message,
run,
work,
+ liveUi = NO_UI,
+ sources,
persona,
now,
latest,
compact,
liveNote,
canStop = false,
+ uiActions,
+ onUiStateChange,
+ onFollowUp,
}: {
message: ChatMessage | null;
run: RunSnapshot | null;
work: TurnWork | null;
+ /** Interfaces the run streamed, until the saved reply carries them. */
+ liveUi?: UiPart[];
+ /** The conversation's sources as of this answer, by number (the thread's
+ * `ChatTurn.sources`); without them, the answer's own. */
+ sources?: ReadonlyMap<number, SourceItem>;
persona: ChatPersona;
now: Date;
latest: boolean;
@@ -74,6 +95,11 @@ export function AssistantTurn({
liveNote?: string | null;
/** The pane stops a working run on Esc, so the status line says so. */
canStop?: boolean;
+ /** What the buttons of an interface in the reply do. */
+ uiActions?: ChatUiActions;
+ onUiStateChange?: (partId: string, changes: UiStateChange[]) => void;
+ /** Sends a suggested next question; absent where they cannot go. */
+ onFollowUp?: (text: string) => void;
}) {
const queued = run?.state === 'queued';
const live = Boolean(run && isLiveRun(run) && !queued);
@@ -84,6 +110,16 @@ export function AssistantTurn({
const narration = streamed.narration;
const rate = useWritingRate(text, streaming, now);
const failure = run?.state === 'error' ? failureLines(run.error, persona.name) : null;
+ const saved = message ? savedUiParts(message.parts) : NO_UI;
+ const interfaces = saved.length > 0 ? saved : liveUi;
+ // Only under the latest answer, once it is done.
+ const followups = message && latest && !live && onFollowUp ? savedFollowups(message.parts) : [];
+ const citations = useMemo<CitationInfo>(() => {
+ if (!message) return NO_CITATIONS;
+ const known = sources ?? new Map(savedSources(message.parts).map((source) => [source.n, source] as const));
+ if (known.size === 0) return NO_CITATIONS;
+ return { sources: known, order: citationOrder(text, new Set(known.keys())) };
+ }, [message, text, sources]);
return (
<div
@@ -107,10 +143,22 @@ export function AssistantTurn({
)}
>
<Suspense fallback={<p className="m-0 whitespace-pre-wrap">{text}</p>}>
- <ReplyMarkdown text={text} streaming={streaming} />
+ <CitationContext.Provider value={citations}>
+ <ReplyMarkdown text={text} streaming={streaming} />
+ </CitationContext.Provider>
</Suspense>
</div>
)}
+ {uiActions &&
+ interfaces.map((part) => (
+ <GeneratedUiBlock
+ key={part.partId}
+ part={part}
+ live={!message && live}
+ actions={uiActions}
+ onStateChange={onUiStateChange}
+ />
+ ))}
{live && run && (
<StatusLine
label={liveLabel(run, streaming)}
@@ -137,6 +185,8 @@ export function AssistantTurn({
{run?.error?.hint && <p className="m-0">{run.error.hint}</p>}
</Note>
)}
+ {citations.order.size > 0 && <SourceChips sources={citations.sources} order={citations.order} />}
+ {followups.length > 0 && onFollowUp && <FollowUps items={followups} onPick={onFollowUp} />}
{message && <TurnMeta shown={latest}>{timeLabel(message.timestamp, now)}</TurnMeta>}
</div>
</div>
diff --git a/client/src/features/chat/turns/FollowUps.tsx b/client/src/features/chat/turns/FollowUps.tsx
new file mode 100644
index 00000000..51e49772
--- /dev/null
+++ b/client/src/features/chat/turns/FollowUps.tsx
@@ -0,0 +1,45 @@
+/**
+ * What the owner might ask next, under the employee's latest answer (design
+ * handoff chat, "follow-up chips"): up to three short questions the employee
+ * suggested (`parts.followups`). Pressing one sends it as the owner's
+ * message, exactly as it reads. They spring in one after another the first
+ * time they show.
+ */
+
+import { CornerDownLeft } from 'lucide-react';
+import { useLayoutEffect, useRef } from 'react';
+import { Button } from '@/components/ui/button';
+import { stagger, staggerStep } from '@/lib/motion';
+
+export function FollowUps({ items, onPick, disabled = false }: { items: string[]; onPick: (text: string) => void; disabled?: boolean }) {
+ const listRef = useRef<HTMLDivElement>(null);
+ useLayoutEffect(() => {
+ const chips = listRef.current?.querySelectorAll('[data-followup]');
+ if (!chips?.length) return;
+ stagger(chips, [{ opacity: 0, transform: 'translateY(6px)' }, { opacity: 1, transform: 'none' }], {
+ duration: 'follow-in',
+ easing: 'spring',
+ step: staggerStep('follow'),
+ });
+ // Once, when they first show.
+ }, []);
+
+ if (items.length === 0) return null;
+ return (
+ <div ref={listRef} role="group" aria-label="Ask next" className="mt-0.5 flex flex-col items-start gap-1.5">
+ {items.map((text) => (
+ <Button
+ key={text}
+ data-followup
+ variant="quiet"
+ disabled={disabled}
+ onClick={() => onPick(text)}
+ className="h-auto min-h-8 max-w-full justify-start gap-2 rounded-pill border-border-default py-1.25 pr-3 pl-2.5 text-left text-sm font-medium whitespace-normal text-fg-default hover:border-border-strong hover:bg-bg-hover"
+ >
+ <CornerDownLeft aria-hidden className="size-3.25 shrink-0 text-fg-faint" strokeWidth={2} />
+ {text}
+ </Button>
+ ))}
+ </div>
+ );
+}
diff --git a/client/src/features/chat/turns/GeneratedUiBlock.tsx b/client/src/features/chat/turns/GeneratedUiBlock.tsx
new file mode 100644
index 00000000..f273e90d
--- /dev/null
+++ b/client/src/features/chat/turns/GeneratedUiBlock.tsx
@@ -0,0 +1,60 @@
+/**
+ * An interface the employee showed in its reply (design handoff chat,
+ * "Generated UI"), under the reply's text. The renderer loads lazily
+ * (genui/ChatUi.tsx, with json-render); until it has, a dashed shimmer
+ * stands where the interface will be. Development builds also show its size
+ * and the spec and patches it came from.
+ *
+ * `chat-genui` is the theme hook for the block.
+ */
+
+import { Suspense, lazy, useMemo } from 'react';
+import { SpecInspector } from '@/lib/jsonRender/SpecInspector';
+import type { UiStateChange } from '@/lib/jsonRender/uiState';
+import type { UiPart } from '../data/parts';
+import type { ChatUiActions } from '../genui/actions';
+import { prepareChatSpec } from '../genui/prepare';
+
+const ChatUi = lazy(() => import('../genui/ChatUi'));
+
+function DevDetails({ part }: { part: UiPart }) {
+ const spec = useMemo(() => prepareChatSpec(part.spec), [part.spec]);
+ if (!spec) return null;
+ const elements = Object.keys(spec.elements).length;
+ return (
+ <div className="flex flex-col gap-1">
+ <span className="font-mono text-2xs text-fg-faint">
+ {elements} elements{part.patches > 0 ? ` · ${part.patches} patches` : ''}
+ </span>
+ <SpecInspector spec={spec} label="Inspect" />
+ </div>
+ );
+}
+
+export function GeneratedUiBlock({
+ part,
+ live,
+ actions,
+ onStateChange,
+}: {
+ part: UiPart;
+ live: boolean;
+ actions: ChatUiActions;
+ onStateChange?: (partId: string, changes: UiStateChange[]) => void;
+}) {
+ return (
+ <div data-part={part.partId} className="chat-genui flex min-w-0 flex-col gap-2">
+ <Suspense fallback={<div aria-hidden className="opencompany-shimmer-slot h-20 rounded-xl border border-dashed border-border-default" />}>
+ <ChatUi
+ partId={part.partId}
+ spec={part.spec}
+ state={part.state}
+ live={live}
+ actions={actions}
+ onStateChange={onStateChange ? (changes) => onStateChange(part.partId, changes) : undefined}
+ />
+ </Suspense>
+ {import.meta.env.DEV && <DevDetails part={part} />}
+ </div>
+ );
+}
diff --git a/client/src/features/chat/turns/SourceChips.tsx b/client/src/features/chat/turns/SourceChips.tsx
new file mode 100644
index 00000000..9eb4b528
--- /dev/null
+++ b/client/src/features/chat/turns/SourceChips.tsx
@@ -0,0 +1,63 @@
+/**
+ * The sources an answer cites, under it (design handoff chat, "sources"):
+ * one chip per cited source, numbered as the text's citation chips are, with
+ * the site and the title, opening the source in a new tab.
+ */
+
+import { cn } from '@/lib/utils';
+import type { SourceItem } from '../data/parts';
+
+function hostOf(url: string | null): string | null {
+ if (!url) return null;
+ try {
+ return new URL(url).hostname.replace(/^www\./, '');
+ } catch {
+ return null;
+ }
+}
+
+export function SourceChips({ sources, order }: { sources: ReadonlyMap<number, SourceItem>; order: ReadonlyMap<number, number> }) {
+ const cited = [...order.entries()]
+ .sort((a, b) => a[1] - b[1])
+ .flatMap(([n, shown]) => {
+ const source = sources.get(n);
+ return source ? [{ source, shown }] : [];
+ });
+ if (cited.length === 0) return null;
+ return (
+ <ul aria-label="Sources" className="m-0 flex list-none flex-wrap gap-1.5 p-0">
+ {cited.map(({ source, shown }) => {
+ const host = hostOf(source.url);
+ const body = (
+ <>
+ <span className="grid h-4.25 min-w-4.25 shrink-0 place-items-center rounded-pill bg-action-save-soft px-1 font-mono text-2xs font-semibold text-action-save-ink">
+ {shown}
+ </span>
+ {host && <span className="shrink-0 text-fg-muted">{host}</span>}
+ <span className="min-w-0 truncate text-fg-default">{source.title}</span>
+ </>
+ );
+ const chip = 'flex h-7 max-w-72 items-center gap-1.5 rounded-pill border border-border-default bg-bg-panel pr-2.5 pl-1.5 text-xs';
+ return (
+ <li key={source.n} className="min-w-0">
+ {source.url ? (
+ <a
+ href={source.url}
+ target="_blank"
+ rel="noopener noreferrer"
+ title={source.title}
+ className={cn(chip, 'no-underline transition-colors duration-(--dur-default) hover:border-border-strong hover:bg-bg-hover')}
+ >
+ {body}
+ </a>
+ ) : (
+ <span title={source.title} className={chip}>
+ {body}
+ </span>
+ )}
+ </li>
+ );
+ })}
+ </ul>
+ );
+}
diff --git a/client/src/features/chat/turns/UserTurn.tsx b/client/src/features/chat/turns/UserTurn.tsx
index a5e6239c..f806b020 100644
--- a/client/src/features/chat/turns/UserTurn.tsx
+++ b/client/src/features/chat/turns/UserTurn.tsx
@@ -1,25 +1,42 @@
/**
* The owner's message: a bubble on the right (design handoff chat,
- * "Thread"), with when they sent it under it. `chat-msg chat-msg-user` is
- * the theme hook the stylized themes paint.
+ * "Thread"), with when they sent it under it. A button they pressed in an
+ * interface the employee showed (`kind: "action"`) reads as the press: the
+ * button's label beside a pointer, in a quieter pill. `chat-msg
+ * chat-msg-user` is the theme hook the stylized themes paint.
*/
+import { MousePointerClick } from 'lucide-react';
import { cn } from '@/lib/utils';
import type { ChatMessage } from '../data/schemas';
import { timeLabel } from '../thread/timeLabel';
import { TurnMeta } from './TurnMeta';
export function UserTurn({ message, now, latest, compact }: { message: ChatMessage; now: Date; latest: boolean; compact: boolean }) {
+ const pressed = message.kind === 'action';
return (
<div data-turn="user" data-message={message.id} className="chat-turn-user group/turn flex flex-col items-end gap-1.5">
- <p
- className={cn(
- 'chat-msg chat-msg-user m-0 max-w-[85%] rounded-draft rounded-br-sm border border-border-default bg-bg-elevated whitespace-pre-wrap text-fg-default wrap-anywhere',
- compact ? 'px-3 py-2 leading-normal' : 'px-4 py-2.5 text-md leading-normal',
- )}
- >
- {message.text}
- </p>
+ {pressed ? (
+ <p
+ className={cn(
+ 'm-0 flex max-w-[85%] items-center gap-2 rounded-pill border border-border-default bg-bg-panel text-fg-muted wrap-anywhere',
+ compact ? 'px-3 py-1.5 text-sm' : 'px-3.5 py-2 text-sm',
+ )}
+ >
+ <MousePointerClick aria-hidden className="size-3.5 shrink-0 text-fg-faint" strokeWidth={2} />
+ <span className="sr-only">Pressed </span>
+ <span className="font-medium text-fg-default">{message.text}</span>
+ </p>
+ ) : (
+ <p
+ className={cn(
+ 'chat-msg chat-msg-user m-0 max-w-[85%] rounded-draft rounded-br-sm border border-border-default bg-bg-elevated whitespace-pre-wrap text-fg-default wrap-anywhere',
+ compact ? 'px-3 py-2 leading-normal' : 'px-4 py-2.5 text-md leading-normal',
+ )}
+ >
+ {message.text}
+ </p>
+ )}
<TurnMeta shown={latest || message.pending}>{message.pending ? 'Sending…' : timeLabel(message.timestamp, now)}</TurnMeta>
</div>
);
diff --git a/client/src/lib/agui/__tests__/patch.test.ts b/client/src/lib/agui/__tests__/patch.test.ts
new file mode 100644
index 00000000..6643937f
--- /dev/null
+++ b/client/src/lib/agui/__tests__/patch.test.ts
@@ -0,0 +1,53 @@
+/**
+ * Patches on an activity's content (lib/agui/patch.ts): add, replace and
+ * remove, never through a prototype key, never changing the input, and an
+ * operation that does not apply is skipped. The same cases as the server's
+ * tests/services/genui/test_patches.py.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { applyPatch, applyPatchOp, type PatchOp } from '../patch';
+
+describe('applyPatchOp', () => {
+ it('adds, replaces and removes without touching the input', () => {
+ const content = { a: { b: [1, 2] } };
+ expect(applyPatchOp(content, { op: 'add', path: '/a/c', value: 3 })).toEqual({ a: { b: [1, 2], c: 3 } });
+ expect(applyPatchOp(content, { op: 'add', path: '/a/b/1', value: 9 })).toEqual({ a: { b: [1, 9, 2] } });
+ expect(applyPatchOp(content, { op: 'add', path: '/a/b/-', value: 9 })).toEqual({ a: { b: [1, 2, 9] } });
+ expect(applyPatchOp(content, { op: 'replace', path: '/a/b/0', value: 7 })).toEqual({ a: { b: [7, 2] } });
+ expect(applyPatchOp(content, { op: 'remove', path: '/a/b/0' })).toEqual({ a: { b: [2] } });
+ expect(applyPatchOp(content, { op: 'remove', path: '/a' })).toEqual({});
+ expect(applyPatchOp(content, { op: 'replace', path: '', value: { fresh: 1 } })).toEqual({ fresh: 1 });
+ expect(content).toEqual({ a: { b: [1, 2] } });
+ });
+
+ it.each<PatchOp>([
+ { op: 'add', path: '/__proto__/polluted', value: true },
+ { op: 'add', path: '/a/constructor', value: 1 },
+ { op: 'replace', path: '/missing', value: 1 },
+ { op: 'remove', path: '/missing' },
+ { op: 'add', path: '/a/x/y', value: 1 },
+ { op: 'add', path: '/a/b/5', value: 1 },
+ { op: 'replace', path: '/a/b/-', value: 1 },
+ { op: 'move', path: '/b' },
+ { op: 'add', path: 'no-slash', value: 1 },
+ ])('skips $op $path', (op) => {
+ const content = { a: { b: [1, 2] } };
+ expect(applyPatchOp(content, op)).toBe(content);
+ expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+ });
+
+ it('folds a stream in order', () => {
+ const built = applyPatch({ root: '', state: {}, elements: {} }, [
+ { op: 'add', path: '/root', value: 'r' },
+ { op: 'add', path: '/state', value: { slot: 's2' } },
+ { op: 'add', path: '/elements/r', value: { type: 'Stack', props: {} } },
+ { op: 'add', path: '/elements/a~1b', value: { type: 'Text', props: { text: 'x' } } },
+ ]);
+ expect(built).toEqual({
+ root: 'r',
+ state: { slot: 's2' },
+ elements: { r: { type: 'Stack', props: {} }, 'a/b': { type: 'Text', props: { text: 'x' } } },
+ });
+ });
+});
diff --git a/client/src/lib/agui/__tests__/reduceRun.test.ts b/client/src/lib/agui/__tests__/reduceRun.test.ts
index 700ba86f..858916cc 100644
--- a/client/src/lib/agui/__tests__/reduceRun.test.ts
+++ b/client/src/lib/agui/__tests__/reduceRun.test.ts
@@ -1,11 +1,13 @@
/**
* A chat run folded from its events: the handoff's Saturday booking run
- * (steps, streamed text, a draft waiting for the owner, then the resume run
- * that sent it), duplicates, and the snapshots the server sends.
+ * (steps, streamed text, a generated interface patch by patch, a draft
+ * waiting for the owner, then the resume run that sent it), duplicates, and
+ * the snapshots the server sends.
*/
import { describe, expect, it } from 'vitest';
import fixture from '@/features/chat/__fixtures__/saturday-booking.events.json';
+import booking from '@/features/chat/__fixtures__/saturday-booking.spec.json';
import { parseRunFrame, type RunEvent } from '../events';
import { applyRunEvent, emptyRun, isLiveRun, replayRun, snapshotFromWire } from '../reduceRun';
@@ -65,6 +67,39 @@ describe('applyRunEvent', () => {
expect(isLiveRun(run)).toBe(false);
});
+ it('builds the interface the run streamed, patch by patch', () => {
+ const run = replayRun('r_8f2a1c', 'wf_salon', eventsOf('r_8f2a1c'));
+ const ui = run.activities.find((activity) => activity.activityType === 'json_render');
+ expect(ui).toMatchObject({ messageId: 'p_ui_1', patches: 13 });
+ expect(ui?.content).toEqual({
+ root: booking.root,
+ state: booking.state,
+ elements: booking.elements,
+ });
+ });
+
+ it('keeps an activity a snapshot does not replace', () => {
+ const base = applyRunEvent(
+ emptyRun('r1', 'w1'),
+ parseRunFrame(envelope('activity.snapshot', { message_id: 'p', activity_type: 'json_render', content: { root: 'a' } })) as RunEvent,
+ );
+ const kept = applyRunEvent(
+ base,
+ parseRunFrame(envelope('activity.snapshot', { message_id: 'p', activity_type: 'json_render', content: {}, replace: false }, 2)) as RunEvent,
+ );
+ expect(kept.activities).toEqual([{ messageId: 'p', activityType: 'json_render', content: { root: 'a' }, patches: 0 }]);
+ });
+
+ it('reads activity events and refuses malformed ones', () => {
+ expect(parseRunFrame(envelope('activity.delta', { message_id: 'p', activity_type: 'json_render', patch: [{ op: 'add', path: '/root', value: 'r' }] }))).toMatchObject({
+ type: 'activity.delta',
+ messageId: 'p',
+ patch: [{ op: 'add', path: '/root', value: 'r' }],
+ });
+ expect(parseRunFrame(envelope('activity.delta', { message_id: 'p', activity_type: 'json_render', patch: 'nope' }))).toBeNull();
+ expect(parseRunFrame(envelope('activity.snapshot', { activity_type: 'json_render', content: {} }))).toBeNull();
+ });
+
it('folds the resume run that sent the draft', () => {
const resume = eventsOf('r_8f2a1c').length;
const others = frames.slice(resume).filter((frame): frame is RunEvent => frame !== null && frame.type !== 'resync');
diff --git a/client/src/lib/agui/events.ts b/client/src/lib/agui/events.ts
index 33a224c3..63e9dc4e 100644
--- a/client/src/lib/agui/events.ts
+++ b/client/src/lib/agui/events.ts
@@ -10,9 +10,11 @@
*
* Fields beyond the scope are read one at a time: a field that cannot be read
* is left out, never the whole event. Suffixes later phases render
- * (tool calls, activities, reasoning) come back as `unhandled`.
+ * (tool calls, reasoning) come back as `unhandled`.
*/
+import type { PatchOp } from './patch';
+
export const RUN_SOURCE = 'opencompany://services/chat';
export const RUN_TYPE_PREFIX = 'com.opencompany.chat.run.';
@@ -80,6 +82,8 @@ export type RunEventBody =
| { type: 'text.started'; messageId: string }
| { type: 'text.content'; messageId: string; delta: string }
| { type: 'text.ended'; messageId: string; final: boolean; replyMessageId?: string }
+ | { type: 'activity.snapshot'; messageId: string; activityType: string; content: unknown; replace: boolean }
+ | { type: 'activity.delta'; messageId: string; activityType: string; patch: PatchOp[] }
| { type: 'custom'; name: string; value: Record<string, unknown> }
| { type: 'unhandled'; suffix: string };
@@ -103,11 +107,11 @@ const UNHANDLED_SUFFIXES = new Set([
'tool_call.args',
'tool_call.ended',
'tool_call.result',
- 'activity.snapshot',
- 'activity.delta',
'reasoning.started',
'reasoning.ended',
]);
+/** Patch operations kept per `activity.delta`. */
+const MAX_PATCH_OPS = 64;
type Data = Record<string, unknown>;
@@ -228,6 +232,20 @@ function eventFields(suffix: string, data: Data): RunEventBody | null {
replyMessageId: text(data.reply_message_id),
});
}
+ case 'activity.snapshot':
+ case 'activity.delta': {
+ const messageId = text(data.message_id);
+ const activityType = text(data.activity_type);
+ if (!messageId || !activityType) return null;
+ if (suffix === 'activity.snapshot') {
+ return { type: 'activity.snapshot', messageId, activityType, content: data.content ?? null, replace: data.replace !== false };
+ }
+ if (!Array.isArray(data.patch)) return null;
+ const patch = data.patch
+ .slice(0, MAX_PATCH_OPS)
+ .filter((op): op is PatchOp => isRecord(op) && typeof op.op === 'string' && typeof op.path === 'string');
+ return { type: 'activity.delta', messageId, activityType, patch };
+ }
case 'custom': {
const name = text(data.name);
return name ? { type: 'custom', name, value: isRecord(data.value) ? data.value : {} } : null;
diff --git a/client/src/lib/agui/patch.ts b/client/src/lib/agui/patch.ts
new file mode 100644
index 00000000..26ccde72
--- /dev/null
+++ b/client/src/lib/agui/patch.ts
@@ -0,0 +1,96 @@
+/**
+ * RFC 6902 patches on an activity's content (`activity.delta`,
+ * docs-internal/chat_protocol.md): `add`, `replace` and `remove`, the three
+ * the server writes, applied without touching the input. A path through
+ * `__proto__`, `constructor` or `prototype`, or one that leads nowhere,
+ * leaves the content as it was; so does any other op. The same rules as
+ * server/services/genui/patches.py `apply_patch`.
+ */
+
+import { isForbiddenSegment, unescapePointer } from '@/lib/jsonRender/paths';
+
+export interface PatchOp {
+ op: string;
+ path: string;
+ value?: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function segmentsOf(path: string): string[] | null {
+ if (path === '') return [];
+ if (!path.startsWith('/')) return null;
+ const segments = path.slice(1).split('/').map(unescapePointer);
+ return segments.some(isForbiddenSegment) ? null : segments;
+}
+
+/** `content` with one operation applied; the same object when it does not apply. */
+export function applyPatchOp(content: unknown, op: PatchOp): unknown {
+ if (op.op !== 'add' && op.op !== 'replace' && op.op !== 'remove') return content;
+ const segments = segmentsOf(op.path);
+ if (segments === null) return content;
+ if (segments.length === 0) return op.op === 'remove' ? content : op.value;
+
+ let refused = false;
+ const write = (node: unknown, index: number): unknown => {
+ const key = segments[index];
+ const last = index === segments.length - 1;
+ if (Array.isArray(node)) {
+ const at = key === '-' ? node.length : Number(key);
+ if (!Number.isInteger(at) || at < 0 || at > node.length || (key === '-' && op.op !== 'add')) {
+ refused = true;
+ return node;
+ }
+ const copy = node.slice();
+ if (!last) {
+ if (at >= node.length) {
+ refused = true;
+ return node;
+ }
+ copy[at] = write(node[at], index + 1);
+ return copy;
+ }
+ if (op.op === 'add') copy.splice(at, 0, op.value);
+ else if (at >= node.length) refused = true;
+ else if (op.op === 'replace') copy[at] = op.value;
+ else copy.splice(at, 1);
+ return refused ? node : copy;
+ }
+ if (!isRecord(node)) {
+ refused = true;
+ return node;
+ }
+ const has = Object.prototype.hasOwnProperty.call(node, key);
+ if (!last) {
+ if (!has) {
+ refused = true;
+ return node;
+ }
+ return { ...node, [key]: write(node[key], index + 1) };
+ }
+ if (op.op === 'remove') {
+ if (!has) {
+ refused = true;
+ return node;
+ }
+ const copy = { ...node };
+ delete copy[key];
+ return copy;
+ }
+ if (op.op === 'replace' && !has) {
+ refused = true;
+ return node;
+ }
+ return { ...node, [key]: op.value };
+ };
+ const next = write(content, 0);
+ return refused ? content : next;
+}
+
+/** `content` with every operation applied in order, each one that does not
+ * apply skipped. */
+export function applyPatch(content: unknown, ops: readonly PatchOp[]): unknown {
+ return ops.reduce(applyPatchOp, content);
+}
diff --git a/client/src/lib/agui/reduceRun.ts b/client/src/lib/agui/reduceRun.ts
index c401161c..ed173feb 100644
--- a/client/src/lib/agui/reduceRun.ts
+++ b/client/src/lib/agui/reduceRun.ts
@@ -20,6 +20,7 @@ import {
type RunState,
type StepState,
} from './events';
+import { applyPatch } from './patch';
export interface RunStep {
stepId: string;
@@ -39,6 +40,16 @@ export interface RunSegment {
final: boolean | null;
}
+/** A part the run is building (generated UI, sources, ...), as its
+ * `activity.*` events have it so far. `messageId` is the part's id. */
+export interface RunActivity {
+ messageId: string;
+ activityType: string;
+ content: unknown;
+ /** Patches applied since the snapshot ("Rendering UI · patch k"). */
+ patches: number;
+}
+
export interface RunSnapshot {
runId: string;
sessionId: string;
@@ -58,6 +69,7 @@ export interface RunSnapshot {
durationMs: number | null;
steps: RunStep[];
segments: RunSegment[];
+ activities: RunActivity[];
outcome: RunOutcome | null;
result: RunResult;
error: RunError | null;
@@ -87,6 +99,7 @@ export function emptyRun(runId: string, sessionId: string): RunSnapshot {
durationMs: null,
steps: [],
segments: [],
+ activities: [],
outcome: null,
result: {},
error: null,
@@ -154,6 +167,18 @@ function wireSegments(raw: unknown): RunSegment[] {
});
}
+function wireActivities(raw: unknown): RunActivity[] {
+ if (!Array.isArray(raw)) return [];
+ return raw.flatMap((item) => {
+ if (!isRecord(item)) return [];
+ const messageId = optionalText(item.message_id);
+ const activityType = optionalText(item.activity_type);
+ if (!messageId || !activityType) return [];
+ const patches = typeof item.patches === 'number' && item.patches >= 0 ? item.patches : 0;
+ return [{ messageId, activityType, content: item.content ?? null, patches }];
+ });
+}
+
/** A run as the server sends it (`chat_subscribe`'s `active_runs`,
* `get_chat_run`'s `run`); null when it names no run. */
export function snapshotFromWire(raw: unknown): RunSnapshot | null {
@@ -179,6 +204,7 @@ export function snapshotFromWire(raw: unknown): RunSnapshot | null {
durationMs: typeof raw.duration_ms === 'number' && raw.duration_ms >= 0 ? raw.duration_ms : null,
steps: stepsFromWire(raw.steps),
segments: wireSegments(raw.segments),
+ activities: wireActivities(raw.activities),
outcome,
result: parseResult(raw.result),
// A failed run keeps its hint beside the error, in `result`.
@@ -200,6 +226,17 @@ function withSegment(segments: RunSegment[], messageId: string, update: (segment
return segments.map((segment, i) => (i === index ? update(segment) : segment));
}
+function withActivity(
+ activities: RunActivity[],
+ messageId: string,
+ activityType: string,
+ update: (activity: RunActivity) => RunActivity,
+): RunActivity[] {
+ const index = activities.findIndex((activity) => activity.messageId === messageId);
+ if (index === -1) return [...activities, update({ messageId, activityType, content: null, patches: 0 })];
+ return activities.map((activity, i) => (i === index ? update(activity) : activity));
+}
+
/** `run` with `event` folded in. An event at or before the run's `seq` is a
* duplicate: the same object comes back. */
export function applyRunEvent(run: RunSnapshot, event: RunEvent): RunSnapshot {
@@ -265,6 +302,24 @@ export function applyRunEvent(run: RunSnapshot, event: RunEvent): RunSnapshot {
segments: withSegment(run.segments, event.messageId, (segment) => ({ ...segment, final: event.final })),
replyMessageId: event.replyMessageId ?? run.replyMessageId,
};
+ case 'activity.snapshot':
+ return {
+ ...next,
+ activities: withActivity(run.activities, event.messageId, event.activityType, (activity) =>
+ event.replace || activity.content === null
+ ? { ...activity, activityType: event.activityType, content: event.content, patches: 0 }
+ : activity,
+ ),
+ };
+ case 'activity.delta':
+ return {
+ ...next,
+ activities: withActivity(run.activities, event.messageId, event.activityType, (activity) => ({
+ ...activity,
+ content: applyPatch(activity.content, event.patch),
+ patches: activity.patches + event.patch.length,
+ })),
+ };
case 'custom':
if (event.name === 'opencompany.segment_discarded') {
const discarded = event.value.message_id;