@adecore/agents-react 0.23.0 → 0.24.0

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';