Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(chat): generated UI, follow-ups and citations in replies
trohitg977383cfaafc
diff --git a/client/eslint.config.js b/client/eslint.config.jsindex 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.tsxindex 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<ChatPaneHandif (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<ChatPaneHandliveNote={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.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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, onRefuconst 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, onRefurole: '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, onRefudelivery: 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.tsxindex 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.tsindex 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<Recoconst 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<Recoif (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.tsxindex 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 && (<StatusLinelabel={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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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: (segmentreturn 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;