@adecore/agents-react 0.23.1 → 0.24.1

package/src/chat/ui/rows/WorkRows.tsx

@@ -1,22 +1,38 @@
-import { Suspense, useEffect, useState, type Dispatch, type ReactNode, type SetStateAction } from 'react';
+import { Fragment, Suspense, useEffect, useState, type Dispatch, type ReactNode, type SetStateAction } from 'react';
 import clsx from 'clsx';
 import i18next from 'i18next';
 import { useTranslation } from 'react-i18next';
 import { ChevronRight, FileDiff, X } from 'lucide-react';
 import type { ChatCheckpointDiff, ChatCheckpointFile, ChatFileChange, ChatToolItem, ChatTurnItem } from '@adecore/agent-contracts';
 import type { BaseMoved } from '../../logic/timeline';
-import { fileChanges, liveOutput, readImagePath, toolStartedAt, toolSummary, unifiedChanges, type FileChange } from '../../logic/tools';
+import {
+    exitCodeOf,
+    fileChanges,
+    hasOutput,
+    hasToolBody,
+    liveOutput,
+    readImagePath,
+    shellCommand,
+    toolCallLines,
+    toolStartedAt,
+    toolSummary,
+    toolSummaryIsPath,
+    unifiedChanges,
+    type FileChange
+} from '../../logic/tools';
 import { useOpenForFind } from '../find-reveal';
-import { chatHost } from '../../../host';
+import { useChatHost } from '../../../host';
 import { lazyNamed } from '../../../lazy';
 import { useChatActions } from '../../actions';
 import { useChatScope } from '../../../scope';
 import { useCurrentItem } from '../../../state/chats';
 import { useTimelineFlash } from '../../timeline-flash';
 import { formatClockDuration, formatElapsedShort } from '@adecore/ui/format';
-import { Icon, Spinner, useTickingText } from '@adecore/ui';
+import { Icon, MiddleTruncate, Spinner, useTickingText } from '@adecore/ui';
 import { ROW_GUTTER, toolIcon } from '../icons';
 import { AnsiOutput } from '../AnsiOutput';
+import { RowTime } from '../RowTime';
+import { ShellCommand } from '../ShellCommand';
 import { DiffStack, ReviewStackView } from '../diff/DiffStack';
 import { reviewEntries, type ReviewEntry } from '../diff/review-plan';
 import { useReviewStack } from '../diff/use-review-stack';
@@ -26,54 +42,79 @@ const UnifiedDiff = lazyNamed(() => import('../UnifiedDiff'), 'default');
 
 const OUTPUT_LIMIT = 4000;
 
+/* The line that says how much of a text past the limit is left out; empty for a text within it. */
+function clipNotice(text: string): string {
+    return text.length > OUTPUT_LIMIT ? `\n${i18next.t('agent-chat:work.moreCharacters', { count: text.length - OUTPUT_LIMIT })}` : '';
+}
+
 function clip(text: string): string {
-    return text.length > OUTPUT_LIMIT
-        ? `${text.slice(0, OUTPUT_LIMIT)}\n${i18next.t('agent-chat:work.moreCharacters', { count: text.length - OUTPUT_LIMIT })}`
-        : text;
+    return text.slice(0, OUTPUT_LIMIT) + clipNotice(text);
 }
 
+/*
+ * The line of a call, a subagent or a group. Without `onToggle` it has nothing to open: no chevron, and
+ * not a button. `time` shows at the right edge while the line is hovered or focused.
+ */
 export function ToggleLine({
     icon,
     label,
     detail,
-    open,
+    command,
+    path,
+    open = false,
     onToggle,
     failed,
     live,
     trailing,
+    time,
     className
 }: {
     icon: ReactNode;
     label: string;
     detail?: string;
-    open: boolean;
-    onToggle(): void;
+    /* Draws `detail` as a shell command, in the colors of the code theme. */
+    command?: boolean;
+    /* `detail` is the path of a file, cut in the middle so its name stays in sight. */
+    path?: boolean;
+    open?: boolean;
+    onToggle?(): void;
     failed?: boolean;
     live?: boolean;
     trailing?: ReactNode;
+    time?: number;
     className?: string;
 }) {
-    return (
-        <button
-            className={clsx(
-                // Fix the width so long commands reach the truncation inside the negative margins.
-                '-mx-1 mb-0.5 flex h-7 w-[calc(100%+8px)] items-center gap-2 rounded-md px-1 text-left text-xs text-text-muted hover:bg-surface-hover',
-                failed && 'text-status-error',
-                className
-            )}
-            onClick={onToggle}
-        >
+    const classes = clsx(
+        // Fix the width so long commands reach the truncation inside the negative margins.
+        'group/line -mx-1 mb-0.5 flex h-7 w-[calc(100%+8px)] items-center gap-2 rounded-md px-1 text-left text-xs text-text-muted',
+        onToggle !== undefined && 'hover:bg-surface-hover',
+        failed && 'text-status-error',
+        className
+    );
+    const content = (
+        <>
             <span className={clsx(ROW_GUTTER, live && 'text-accent')}>{icon}</span>
             <span className={clsx('shrink-0', live && 'chat-live-text')}>{label}</span>
             {detail && (
                 <span data-find-field="summary" className="min-w-0 truncate font-mono text-text-faint">
-                    {detail}
+                    {command ? <ShellCommand command={detail} /> : path ? <MiddleTruncate text={detail} /> : detail}
                 </span>
             )}
             <span className="grow" />
             {trailing}
+            {time !== undefined && <RowTime at={time} />}
             {failed && <Icon icon={X} size={12} className="shrink-0" />}
-            <Icon icon={ChevronRight} size={12} className={clsx('shrink-0 text-text-faint transition-transform', open && 'rotate-90')} />
+            {onToggle !== undefined && (
+                <Icon icon={ChevronRight} size={12} className={clsx('shrink-0 text-text-faint transition-transform', open && 'rotate-90')} />
+            )}
+        </>
+    );
+    if (onToggle === undefined) {
+        return <div className={classes}>{content}</div>;
+    }
+    return (
+        <button className={classes} onClick={onToggle}>
+            {content}
         </button>
     );
 }
@@ -106,7 +147,7 @@ function ChangedFileLine({
                 onClick={onToggle}
             >
                 <Icon icon={ChevronRight} size={12} className={clsx('shrink-0 text-text-faint transition-transform', open && 'rotate-90')} />
-                <span className="min-w-0 truncate font-mono text-text">{path}</span>
+                <MiddleTruncate text={path} className="font-mono text-text" />
                 <span className="grow" />
                 {trailing}
             </button>
@@ -115,19 +156,12 @@ function ChangedFileLine({
     );
 }
 
-function ToolBody({ tool }: { tool: ChatToolItem }) {
-    const patches = unifiedChanges(tool);
-    const changes = patches.length > 0 ? [] : fileChanges(tool.name, tool.input);
+/* A diff keeps its card, with what the call answered under it. */
+function DiffBody({ tool, entries, patched }: { tool: ChatToolItem; entries: readonly ReviewEntry[]; patched: boolean }) {
     return (
         <div className="mt-1.5 mb-2 ml-6 overflow-hidden rounded-md border border-border bg-surface-raised">
-            {patches.length + changes.length > 0 ? (
-                <DiffStack entries={reviewEntries(patches, changes)} />
-            ) : (
-                <pre className="max-h-64 overflow-auto px-3 py-2 font-mono text-code text-text-muted select-text">
-                    {clip(JSON.stringify(tool.input, null, 2) ?? '')}
-                </pre>
-            )}
-            {tool.output !== null && tool.output !== '' && patches.length === 0 && (
+            <DiffStack entries={entries} />
+            {hasOutput(tool.output) && !patched && (
                 <pre
                     data-find-field="output"
                     className={clsx(
@@ -142,9 +176,64 @@ function ToolBody({ tool }: { tool: ChatToolItem }) {
     );
 }
 
+/* What a call answered, muted under the call; a failure in the error color, or its exit code when the tool names one. */
+function ToolOutput({ tool }: { tool: ChatToolItem }) {
+    const { t } = useTranslation('agent-chat');
+    if (!hasOutput(tool.output)) {
+        return null;
+    }
+    const failed = tool.state === 'error';
+    const { code, rest } = failed ? exitCodeOf(tool.output) : { code: null, rest: tool.output };
+    return (
+        <>
+            {hasOutput(rest) && (
+                <pre
+                    data-find-field="output"
+                    className={clsx('max-h-64 overflow-auto whitespace-pre-wrap', failed && code === null ? 'text-status-error' : 'text-text-muted')}
+                >
+                    <AnsiOutput text={rest} limit={OUTPUT_LIMIT} />
+                </pre>
+            )}
+            {code !== null && <div className="text-status-error">{t('work.exitCode', { code: String(code) })}</div>}
+        </>
+    );
+}
+
+/* An opened call without a card: what it was asked in the foreground, what it answered muted below. */
+function ToolBody({ tool }: { tool: ChatToolItem }) {
+    const patches = unifiedChanges(tool);
+    const changes = patches.length > 0 ? [] : fileChanges(tool.name, tool.input);
+    if (patches.length + changes.length > 0) {
+        return <DiffBody tool={tool} entries={reviewEntries(patches, changes)} patched={patches.length > 0} />;
+    }
+    const lines = toolCallLines(tool.name, tool.input);
+    return (
+        <div className="mt-0.5 mb-2 ml-6 flex flex-col gap-1.5 font-mono text-code select-text">
+            {lines.command !== null && (
+                <pre className="max-h-64 overflow-auto whitespace-pre-wrap wrap-anywhere text-text">
+                    <ShellCommand command={lines.command.slice(0, OUTPUT_LIMIT)} />
+                    {clipNotice(lines.command)}
+                </pre>
+            )}
+            {lines.args.length > 0 && (
+                <dl className="grid max-h-64 grid-cols-[auto_minmax(0,1fr)] gap-x-3 overflow-auto">
+                    {lines.args.map(([key, value]) => (
+                        <Fragment key={key}>
+                            <dt className="text-text-faint">{key}</dt>
+                            <dd className="whitespace-pre-wrap wrap-anywhere text-text">{clip(value)}</dd>
+                        </Fragment>
+                    ))}
+                </dl>
+            )}
+            {lines.text !== null && <pre className="max-h-64 overflow-auto whitespace-pre-wrap wrap-anywhere text-text">{clip(lines.text)}</pre>}
+            <ToolOutput tool={tool} />
+        </div>
+    );
+}
+
 /*
- * One settled tool call: a line, and its input and output behind it. An image the call looked at is
- * drawn under the line. `icon`, `label` and `failed` let a row that knows the call better name it.
+ * One settled tool call: a line, and what it was asked and answered behind it. An image the call
+ * looked at is drawn under the line. `icon`, `label` and `failed` let a row that knows the call better name it.
  */
 export function WorkRow({
     tool,
@@ -161,22 +250,28 @@ export function WorkRow({
     label?: string;
     failed?: boolean;
 }) {
+    const host = useChatHost();
     const [open, setOpen] = useState(false);
     const image = tool.state === 'done' ? readImagePath(tool.name, tool.input) : null;
-    const { ReadImage } = chatHost();
+    const { ReadImage } = host;
     useOpenForFind(tool.id, 'output', setOpen);
+    const summary = detail ?? toolSummary(tool.name, tool.input);
+    const opens = hasToolBody(tool);
     return (
         <div data-find-item={tool.id} className={nested ? 'ml-6' : undefined}>
             <ToggleLine
                 icon={icon ?? toolIcon(tool.name)}
                 label={label ?? tool.name}
-                detail={detail ?? toolSummary(tool.name, tool.input)}
-                open={open}
-                onToggle={() => setOpen((o) => !o)}
+                detail={summary}
+                command={detail === undefined && summary === shellCommand(tool.name, tool.input)}
+                path={detail === undefined && toolSummaryIsPath(tool.name, tool.input)}
+                open={open && opens}
+                onToggle={opens ? () => setOpen((o) => !o) : undefined}
                 failed={failed ?? tool.state === 'error'}
+                time={tool.createdAt}
             />
             {image !== null && ReadImage !== null && <ReadImage path={image} />}
-            {open && <ToolBody tool={tool} />}
+            {open && opens && <ToolBody tool={tool} />}
         </div>
     );
 }
@@ -193,18 +288,22 @@ export function WorkLiveRow({ chatId, tool: derived }: { chatId: string; tool: C
     const [open, setOpen] = useState(false);
     const tool = useCurrentItem(chatId, derived);
     const tail = liveOutput(tool);
+    const summary = toolSummary(tool.name, tool.input);
+    const opens = hasToolBody(tool);
     return (
         <div>
             <ToggleLine
                 icon={toolIcon(tool.name)}
                 label={tool.name}
-                detail={toolSummary(tool.name, tool.input) || tool.progress?.description || ''}
-                open={open}
-                onToggle={() => setOpen((o) => !o)}
+                detail={summary || tool.progress?.description || ''}
+                command={summary !== '' && summary === shellCommand(tool.name, tool.input)}
+                path={summary !== '' && toolSummaryIsPath(tool.name, tool.input)}
+                open={open && opens}
+                onToggle={opens ? () => setOpen((o) => !o) : undefined}
                 trailing={<RunningFor startedAt={toolStartedAt(tool)} />}
                 live
             />
-            {open && <ToolBody tool={tool} />}
+            {open && opens && <ToolBody tool={tool} />}
             {tail !== null && !open && (
                 <pre className="mt-1.5 mb-2 ml-6 max-h-48 overflow-auto rounded-md border border-border bg-surface-raised px-3 py-2 font-mono text-code whitespace-pre-wrap text-chat-output select-text">
                     <AnsiOutput text={tail} tailLines={12} />
@@ -219,7 +318,7 @@ export function WorkGroupRow({ tools, summary, expanded, onToggle }: { tools: Ch
     const failed = tools.some((tool) => tool.state === 'error');
     return (
         <div>
-            <ToggleLine icon={toolIcon(tools[0]!.name)} label={summary} open={expanded} onToggle={onToggle} failed={failed} />
+            <ToggleLine icon={toolIcon(tools[0]!.name)} label={summary} open={expanded} onToggle={onToggle} failed={failed} time={tools[0]!.createdAt} />
         </div>
     );
 }
@@ -244,7 +343,7 @@ export function TurnFoldRow({
     return (
         <button
             className={clsx(
-                'group -mx-1 mb-2 flex h-7 w-[calc(100%+8px)] min-w-0 items-center gap-2 rounded-md px-1 text-left text-xs text-text-muted hover:bg-surface-hover',
+                'group group/line -mx-1 mb-2 flex h-7 w-[calc(100%+8px)] min-w-0 items-center gap-2 rounded-md px-1 text-left text-xs text-text-muted hover:bg-surface-hover',
                 turn.state === 'error' && 'text-status-error'
             )}
             aria-expanded={expanded}
@@ -255,6 +354,8 @@ export function TurnFoldRow({
             </span>
             <span className="shrink-0 group-hover:text-text">{label}</span>
             {work.length > 0 && <span className="min-w-0 truncate text-text-faint">{work.map((part) => ` · ${part}`).join('')}</span>}
+            <span className="grow" />
+            <RowTime at={turn.createdAt} />
         </button>
     );
 }

package/src/chat/ui/rows/WorkflowRow.tsx

@@ -9,7 +9,7 @@ import { RunningFor, ToggleLine, WorkLiveRow, WorkRow } from './WorkRows';
 import { useChatScope } from '../../../scope';
 import { Icon, IconButton } from '@adecore/ui';
 import { useChatActions } from '../../actions';
-import { chatHost } from '../../../host';
+import { useChatHost } from '../../../host';
 
 function AgentLine({ view, onOpen }: { view: WorkflowAgentView; onOpen?(step: SubagentStep): void }) {
     const { agent, state } = view;
@@ -75,6 +75,7 @@ export function WorkflowRow({
     chatId?: string;
     onOpenAgent?(step: SubagentStep): void;
 }) {
+    const host = useChatHost();
     const { t } = useTranslation('agent-chat');
     const { id } = useChatScope();
     // A host that does not answer `chat.subagent` has no conversation to open for anyone.
@@ -86,7 +87,7 @@ export function WorkflowRow({
     const stop = (): void => {
         if (chatId && workflow.taskId) {
             void actions.stopTask(chatId, workflow.taskId).catch((error: unknown) => {
-                chatHost().notify({
+                host.notify({
                     kind: 'error',
                     title: t('activity.stopFailed'),
                     description: error instanceof Error ? error.message : t('subagents.noAnswer')

package/src/chat/ui/timestamp-format.ts

@@ -0,0 +1,2 @@
+/* The full date and time a row's time names on its tooltip. */
+export const TIMESTAMP_FORMAT: Intl.DateTimeFormatOptions = { dateStyle: 'full', timeStyle: 'medium' };

package/src/chat/ui/use-diff-source-tokens.ts

@@ -1,15 +1,16 @@
 import { useLayoutEffect, useMemo } from 'react';
 import { diffSyntaxDocument, type DiffSourceTokens } from '@adecore/editor-react';
 import type { DiffDocument } from '@adecore/merge';
-import { diffSourceTokens, type DiffSourceTokenSession, type DiffSyntaxRuntime } from './diff-syntax';
+import { useChatHost } from '../../host';
+import { diffSourceTokens, diffSyntaxRuntime, type DiffSourceTokenSession, type DiffSyntaxRuntime } from './diff-syntax';
 
-function createSourceBinding(document: DiffDocument, language: string, theme: string, runtime?: DiffSyntaxRuntime) {
+function createSourceBinding(document: DiffDocument, language: string, theme: string, runtime: () => DiffSyntaxRuntime) {
     const mapping = diffSyntaxDocument(document, language, theme);
     const listeners = new Set<() => void>();
     let source: DiffSourceTokenSession | undefined;
     const current = (): DiffSourceTokenSession => {
         if (source === undefined) {
-            source = diffSourceTokens(document, mapping, runtime);
+            source = diffSourceTokens(document, mapping, runtime());
             source.subscribe(() => {
                 for (const listener of [...listeners]) {
                     listener();
@@ -36,8 +37,13 @@ function createSourceBinding(document: DiffDocument, language: string, theme: st
     };
 }
 
+/* Without a `runtime`, the shared one of the host's `code`. */
 export function useDiffSourceTokens(document: DiffDocument, language: string, theme: string, runtime?: DiffSyntaxRuntime): DiffSourceTokens {
-    const binding = useMemo(() => createSourceBinding(document, language, theme, runtime), [document, language, theme, runtime]);
+    const { code } = useChatHost();
+    const binding = useMemo(
+        () => createSourceBinding(document, language, theme, () => runtime ?? diffSyntaxRuntime(code)),
+        [document, language, theme, runtime, code]
+    );
     useLayoutEffect(() => () => binding.release(), [binding]);
     return binding.tokens;
 }

package/src/chat/ui/visual-theme.ts

@@ -1,6 +1,6 @@
 import { useLayoutEffect, useState, type RefObject } from 'react';
 import { cleanVisualVariables, type VisualAppearance, type VisualTheme, type VisualThemeVariable } from '@adecore/agent-contracts/visual';
-import { chatHost } from '../../host';
+import { useChatHost } from '../../host';
 
 /* The tokens of the app's theme where a frame stands; each answers '' for a token the theme lacks. */
 export interface VisualTokens {
@@ -167,7 +167,8 @@ const THEME_ATTRIBUTES = ['class', 'style', 'data-theme'];
  * accent or a font a person picks reaches every frame as well.
  */
 export function useVisualTheme(ref: RefObject<HTMLElement | null>): VisualTheme | null {
-    const mode = chatHost().code.useMode();
+    const host = useChatHost();
+    const mode = host.code.useMode();
     const [theme, setTheme] = useState<VisualTheme | null>(null);
     useLayoutEffect(() => {
         const element = ref.current;

package/src/host.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps, ComponentType, ReactNode, RefObject } from 'react';
+import { createContext, createElement, useContext, useState, type ComponentProps, type ComponentType, type ReactNode, type RefObject } from 'react';
 import type { Extension } from '@codemirror/state';
 import type { EditorView } from '@codemirror/view';
 import type { Highlighter, ThemeRegistration } from 'shiki';
@@ -7,6 +7,7 @@ import type {
     AgentKind,
     ChatCheckpointDiff,
     ChatConfigurePayload,
+    ChatGoalAction,
     ChatItem,
     ChatSubagentItem,
     ChatUiChoicePayload,
@@ -21,7 +22,6 @@ import type { FindReveal } from './chat/ui/find-reveal';
 import type { PromptAction } from './prompts/logic/prompts';
 import type { HostPrompt, PromptViewProps } from './prompts/logic/subjects';
 import { PlainTextarea } from './ui/PlainTextarea';
-import { configureChatStorage, type ChatStorageOptions } from './storage';
 
 /* A color an account may wear, by the name the host stores it under. */
 export interface AccentChoice {
@@ -58,6 +58,8 @@ export interface ChatActions {
     turnDiff(chatId: string, turnId: string): Promise<ChatCheckpointDiff | null>;
     stopSubagent(chatId: string, toolUseId: string): Promise<void>;
     stopTask(chatId: string, taskId: string): Promise<void>;
+    /* Pauses, resumes or clears the chat's goal; absent where the host offers none of it, which leaves the goal row without its buttons. */
+    goal?(chatId: string, action: ChatGoalAction): Promise<void>;
     approve(chatId: string, requestId: string, decision: 'allow' | 'allow-always' | 'deny', message?: string): Promise<void>;
     answer(chatId: string, requestId: string, answers: Record<string, string>): Promise<void>;
     dismiss(chatId: string, itemId: string): Promise<void>;
@@ -194,13 +196,11 @@ export interface ReplyAuthor {
 }
 
 /*
- * What the app around the chat decides and the chat cannot. Set once, before the first render, with
- * `setChatHost`; whatever an app leaves out keeps the default here, which is the chat without that
- * part. The same in every scope, so a function that is about one host of chats is told its scope id.
- * The hooks are called as hooks: an app hands the same function for the life of the page.
+ * What the app around the chat decides and the chat cannot, handed to the views by a `ChatHostProvider`.
+ * Whatever an app leaves out keeps the default here, which is the chat without that part. One host may
+ * serve several scopes, so a function that is about one host of chats is told its scope id.
  */
 export interface ChatHost {
-    storage?: ChatStorageOptions;
     intelligentUi?: {
         subscribe?(scopeId: string, chatId: string, changed: () => void): () => void;
         link?(scopeId: string, payload: ChatUiLinkPayload): Promise<ChatUiLinkReading>;
@@ -249,7 +249,7 @@ export interface ChatHost {
         syntaxWorker?: () => Worker;
         /* Starts legacy highlighting with its first diff; an enclosing DiffPool takes precedence. */
         legacyDiffWorker?: () => Worker;
-        /* Borrow the page highlighter for fallback; the host retains ownership. */
+        /* Borrow the page highlighter for code blocks and the diff fallback; the host retains ownership. */
         highlighter?: () => Promise<Highlighter>;
         /* Opt in to bounded editor reviews; failures show a status, omitted keeps the legacy renderer. */
         editor?: () => Promise<EditorEngine>;
@@ -310,6 +310,11 @@ export interface ChatHost {
     };
     /* Offers a fork of the chat after one of its turns; null offers none. */
     fork: ((chatId: string, turnId: string) => void) | null;
+    /*
+     * Opens a new chat beside this one on its CLI, model and settings, with the focus in its composer,
+     * once Mod+Alt+Enter sent a message from it; null leaves that key sending the other way, like Alt+Enter.
+     */
+    openNewChat: ((scopeId: string, chatId: string) => void) | null;
     openSettings(section: 'providers' | 'agents'): void;
     /* Whether the host lets a chat go on by itself once a limit it stopped on lifts. */
     useResumeAtReset(scopeId: string): boolean;
@@ -364,6 +369,7 @@ const DEFAULT_HOST: ChatHost = {
     tasks: { useTasks: () => undefined, useTask: () => null },
     confirm: { stopSubagents: (_scopeId, _chatId, run) => run(), stopTask: (_scopeId, _childId, _title, run) => run() },
     fork: null,
+    openNewChat: null,
     openSettings: () => undefined,
     useResumeAtReset: () => true,
     useComposerPlaceholder: () => null,
@@ -374,15 +380,25 @@ const DEFAULT_HOST: ChatHost = {
     visuals: null
 };
 
-let host: ChatHost = DEFAULT_HOST;
+const ChatHostContext = createContext<ChatHost>(DEFAULT_HOST);
 
-export function setChatHost(patch: Partial<ChatHost>): void {
-    if (patch.storage !== undefined) {
-        configureChatStorage(patch.storage);
+/*
+ * Hands the views under it a host: `host` over the one of a provider above it, member by member, and
+ * over the defaults at the top. A part of an app that loads later and adds hooks renders a provider of
+ * its own around what it draws, so every view under it calls the same hooks from its first render on.
+ * The host is read once, as the provider mounts, since a hook that changed under a mounted view would
+ * break the order of its hooks: a provider that gets another `host` throws, and a new `key` remounts it.
+ */
+export function ChatHostProvider({ host, children }: { host: Partial<ChatHost>; children?: ReactNode }) {
+    const parent = useContext(ChatHostContext);
+    const [pinned] = useState(() => ({ host, value: { ...parent, ...host } }));
+    if (pinned.host !== host) {
+        throw new Error('A ChatHostProvider reads its host once: hand it the same object on every render, or a new key to mount it with another');
     }
-    host = { ...host, ...patch };
+    return createElement(ChatHostContext.Provider, { value: pinned.value }, children);
 }
 
-export function chatHost(): ChatHost {
-    return host;
+/* The host of the nearest `ChatHostProvider`, or the defaults outside one. */
+export function useChatHost(): ChatHost {
+    return useContext(ChatHostContext);
 }

package/src/index.ts

@@ -0,0 +1,49 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export {
+    type ChatActions,
+    type FileRef,
+    type ShellCodeBlockContext,
+    type ChatPlace,
+    type SubagentTask,
+    type TimelineFindOptions,
+    type TimelineFind,
+    type ComposerDictationProps,
+    type ComposerSlotProps,
+    type SubagentSlotProps,
+    type ThreadCard,
+    type VisualHost,
+    type ReplyAuthor,
+    type ChatHost,
+    ChatHostProvider,
+    useChatHost,
+    type AccentChoice,
+    type ChatToast,
+    type TextareaProps,
+    type ResourceUrl
+} from './host';
+export { type ChatScope, ChatScopeContext, useChatScope } from './scope';
+export {
+    type ChatRequestMap,
+    type ChatEventMap,
+    type ChatTransportStatus,
+    type ChatTransport,
+    ChatTransportError,
+    errorCode,
+    isConnectionError
+} from './transport';
+export { portTransport, type PortTransport } from './port-transport';
+export {
+    onChatStorageConfiguration,
+    configureChatStorage,
+    chatStorageKey,
+    chatStorageLegacyKeys,
+    chatStorageAdapter,
+    hydrateChatStorage,
+    createChatStore,
+    type ChatStorageRecord,
+    type ChatStorageAdapter,
+    type ChatStorageOptions
+} from './storage';
+export { setLazyPrefetch, onLazyOpenError } from './lazy';
+export { type MountedEntry, MountedRegistry } from './mounted-registry';
+export { type AgentsSettingsSection, PROVIDERS_SECTION, USAGE_SECTION, settingsSection } from './settings/sections';