@adecore/agents-react 0.0.1 → 0.17.0-beta.2

package/src/host.ts

@@ -0,0 +1,324 @@
+import type { ComponentProps, ComponentType, ReactNode, RefObject } from 'react';
+import type { Extension } from '@codemirror/state';
+import type { EditorView } from '@codemirror/view';
+import type { ThemeRegistration } from 'shiki';
+import type { AgentKind, ChatCheckpointDiff, ChatConfigurePayload, ChatItem, ChatSubagentItem } from '@adecore/agent-contracts';
+import { isApplePlatform } from '@adecore/ui';
+import type { TimelineRow } from './chat/logic/timeline';
+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 {
+    id: string;
+    color: string;
+}
+
+export interface ChatToast {
+    /* A toast with the same id replaces the one that is up. */
+    id?: string;
+    title: string;
+    description?: string;
+    /* `deleted` says something went that the action can bring back. */
+    kind: 'success' | 'error' | 'deleted';
+    action?: { label: string; run(): void };
+}
+
+/*
+ * What a person does to a chat from its own surfaces. Without an app's own set, each one is the request
+ * a chat host answers; an app that runs every action through one door (confirmations, voice, an
+ * activity log) hands its own. A refusal throws something with a `code`.
+ */
+export interface ChatActions {
+    clear(chatId: string, force: boolean): Promise<void>;
+    /* With `subagents`, also ends the agents this chat opened. */
+    stopTurn(chatId: string, subagents: boolean): Promise<void>;
+    /* Refused with `request-not-found` when the message already went out. */
+    unqueue(chatId: string, messageId: string): Promise<void>;
+    sendNow(chatId: string, messageId: string): Promise<void>;
+    compact(chatId: string): Promise<void>;
+    configure(chatId: string, patch: Omit<ChatConfigurePayload, 'chatId'>): Promise<void>;
+    continueOn(chatId: string, account: string): Promise<void>;
+    /* Null when the turn has no checkpoint to compare against. */
+    turnDiff(chatId: string, turnId: string): Promise<ChatCheckpointDiff | null>;
+    stopSubagent(chatId: string, toolUseId: string): Promise<void>;
+    stopTask(chatId: string, taskId: string): 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>;
+}
+
+/* A path an answer names, as it was written: absolute, or relative to the folder the chat works in. */
+export interface FileRef {
+    path: string;
+    /* One-based, when the reference named a line. */
+    line?: number;
+    /* A trailing separator is the only thing that says a reference means a directory. */
+    directory: boolean;
+}
+
+/* Where another chat stands and how to get there; a null title is a chat that is gone. */
+export interface ChatPlace {
+    title: string | null;
+    go(): void;
+}
+
+/* The task behind a sub-agent row an app opened with a task of its own (`origin` that is not the CLI's). */
+export interface SubagentTask {
+    status: 'open' | 'done' | 'failed' | 'cancelled';
+    createdAt: number;
+    settledAt: number | null;
+    /* Set while the child waits out a limit, with when it lifts. */
+    paused?: { until?: number };
+}
+
+/* What a find in a thread needs of it, and what it hands back to draw. */
+export interface TimelineFindOptions {
+    chatId: string;
+    /* What the find key looks for, and what the bar stands in. */
+    frame: RefObject<HTMLDivElement | null>;
+    /* Where the rows are drawn, which is what gets marked. */
+    thread: RefObject<HTMLDivElement | null>;
+    scroller: RefObject<HTMLDivElement | null>;
+    enabled: boolean;
+    rows: readonly TimelineRow[];
+    structure: Readonly<Record<string, ChatItem>> | undefined;
+    order: readonly string[] | undefined;
+    /* The first row on screen, where a new search starts looking. */
+    firstRowInView(): number;
+    openTurn(turnId: string): void;
+    openGroup(id: string): void;
+    openSubagent(id: string): void;
+    scrollToRow(index: number): void;
+    /* The height of the composer standing over the end of the scroller. */
+    coveredHeight(): number;
+    stopFollowing(): void;
+}
+
+export interface TimelineFind {
+    open: boolean;
+    /* Drawn over the thread while the find is open. */
+    bar: ReactNode;
+    reveal: FindReveal | null;
+    /* The row each hit is shown at, in the order of the hits. */
+    hitRows: readonly number[];
+    currentRow: number | null;
+}
+
+/* The dictation control beside the composer's editor; it takes its text from the editor itself. */
+export interface ComposerDictationProps {
+    targetRef: RefObject<HTMLElement | null>;
+    /* Where the button goes, in the composer's row of round controls. */
+    buttonContainer: HTMLElement | null | undefined;
+    disabled: boolean;
+    editor(): EditorView | null;
+}
+
+export type TextareaProps = ComponentProps<'textarea'> & {
+    /* Where a button beside the field sits, such as a negative margin so it does not make a one-line row taller. */
+    buttonClassName?: string;
+};
+
+/* An attached file's bytes, as a URL an image or a link can use; `failure` says why there is none. */
+export interface ResourceUrl {
+    url: string | null;
+    failure: string | null;
+}
+
+/* What an app's own control in the composer's row gets. */
+export interface ComposerSlotProps {
+    scopeId: string;
+    chatId: string;
+    disabled: boolean;
+    /* Puts text in the draft at the caret, a space apart from the words beside it, and gives the editor the focus. */
+    insert(text: string): void;
+}
+
+/* What an app's own chips for a chat's sub-agents get, in place of the one flyout over the composer. */
+export interface SubagentSlotProps {
+    chatId: string;
+    /* Never empty: without rows the slot is not drawn. */
+    items: readonly ChatSubagentItem[];
+}
+
+/* A card of the app's own between the messages of a thread. */
+export interface ThreadCard {
+    /* Unique within the chat; the thread keys its row by it, so the same card keeps its place and its measure. */
+    id: string;
+    /* When it happened, in milliseconds on the clock of a chat item's `createdAt`: it follows every row from before then. */
+    at: number;
+    /* Called only while the card is on screen, since the thread draws only the rows in view. */
+    render(): ReactNode;
+}
+
+/* Who writes a chat's replies, as the header over each one names them. */
+export interface ReplyAuthor {
+    name: string;
+    /* Drawn before the name, such as an avatar. */
+    mark?: ReactNode;
+}
+
+/*
+ * 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.
+ */
+export interface ChatHost {
+    storage?: ChatStorageOptions;
+    /* The colors an account may wear in the order a picker offers them, the few it shows first, and their names. */
+    accents: {
+        all: readonly AccentChoice[];
+        featured: readonly string[];
+        label(id: string): string;
+        /* The accent the app is painted in, which an account without a color of its own wears. */
+        current(): string;
+    };
+    isApplePlatform(): boolean;
+    /* A key the app keeps for itself even while the composer has the keyboard, such as the ones that move between views. */
+    isAppShortcut(event: KeyboardEvent): boolean;
+    notify(toast: ChatToast): void;
+    /* The app's own actions; null runs every one as a request on the scope's transport. */
+    actions: ChatActions | null;
+    /* Files under `cwd` for the composer's `@` picker; null offers none. */
+    searchFiles: ((scopeId: string, cwd: string, query: string, limit: number) => Promise<string[]>) | null;
+    /* The bytes of a file attached to a message, where the host keeps them. */
+    attachments: {
+        useUrl(scopeId: string, chatId: string, attachmentId: string): ResourceUrl;
+        read(scopeId: string, chatId: string, attachmentId: string): Promise<Blob>;
+    };
+    /* The image a tool read, drawn under its row; null draws none. */
+    ReadImage: ComponentType<{ path: string }> | null;
+    code: {
+        /* Whether the app is light or dark right now. */
+        useMode(): 'light' | 'dark';
+        /* The Shiki theme ids code is drawn in, one per mode. */
+        useThemes(): { light: string; dark: string };
+        /* Themes the app ships itself, found by name; the rest Shiki looks up by id. */
+        custom: ReadonlyArray<ThemeRegistration & { name: string }>;
+    };
+    /* How a reply appears while it streams: a word, a block or the whole of it at a time. */
+    useStreaming(): 'words' | 'blocks' | 'whole';
+    /* Paths in an answer as links; null leaves them text. */
+    fileLinks: {
+        /* The reference a piece of text names, where the folder it counts from lets it be opened. */
+        target(text: string, cwd: string | null): FileRef | null;
+        open(cwd: string | null, ref: FileRef): void;
+    } | null;
+    /* Find in a thread; without one the thread has no find. */
+    useTimelineFind(options: TimelineFindOptions): TimelineFind;
+    dictation: {
+        /* The field a written answer goes in. */
+        Textarea: ComponentType<TextareaProps>;
+        /* What the composer's editor carries for dictated text, and the control beside it. */
+        composer: { extensions: Extension; Control: ComponentType<ComposerDictationProps> } | null;
+    };
+    prompts: {
+        /* Prompts the app raises beside a chat's own requests, answered in the same place. */
+        useExtra(scopeId: string, chatId: string): readonly HostPrompt[];
+        render(prompt: HostPrompt, props: PromptViewProps): ReactNode;
+        answer(prompt: HostPrompt, action: PromptAction): Promise<void>;
+    };
+    /* Other chats a message may point at with `@`, beside the files. */
+    useReferableChats(): ReadonlyArray<{ id: string; title: string }>;
+    /* Opens the CLI's own login for an account, somewhere the app can run a command; null offers none. */
+    openLogin: ((scopeId: string, kind: AgentKind, accountId: string, name: string) => Promise<void>) | null;
+    /* Why a login cannot start from here right now, or null when it can. */
+    useLoginBlocked(scopeId: string): string | null;
+    /* The name and the mark of a project of the host, for the usage per project; null draws the folder's own. */
+    useProjectLook(scopeId: string, projectId: string | null): { name: string; mark: ReactNode } | null;
+    /* Where another chat of the app stands, for a fork's way back and a note from a fork. */
+    useChatPlace(chatId: string): ChatPlace;
+    /* What a chat may read besides its folder, named under an empty thread. */
+    useContextSources(chatId: string): ReadonlyArray<{ title: string }>;
+    /* Whether the folder a chat works in is the app's business only, so an empty thread does not name it. */
+    useHidesFolder(chatId: string): boolean;
+    /* Whether a chat before its first message opens on a greeting with the composer under it, rather than an empty thread over a docked composer. */
+    useWelcome(chatId: string): boolean;
+    tasks: {
+        useTasks(scopeId: string): Readonly<Record<string, SubagentTask>> | undefined;
+        /* Null for a row with no task behind it. */
+        useTask(scopeId: string, taskId: string | null): SubagentTask | null;
+    };
+    /* Asked before a stop that ends agents the chat opened; `run` stops. */
+    confirm: {
+        stopSubagents(scopeId: string, chatId: string, run: () => void): void;
+        stopTask(scopeId: string, childId: string, title: string, run: () => void): void;
+    };
+    /* Offers a fork of the chat after one of its turns; null offers none. */
+    fork: ((chatId: string, turnId: string) => void) | null;
+    /* Opens the app's settings on a section: `providers`, or `agents`. */
+    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;
+    /* The words an empty composer opens with, before the keys it hints at; null keeps the chat's own. */
+    useComposerPlaceholder(scopeId: string, chatId: string): string | null;
+    /* The app's own control in the composer's row, after the pickers; null draws none. */
+    ComposerSlot: ComponentType<ComposerSlotProps> | null;
+    /* The app's own chips for a chat's sub-agents over the composer; null draws the one flyout. */
+    SubagentSlot: ComponentType<SubagentSlotProps> | null;
+    /* Cards of the app's own in a thread, in any order. Hand back the same array while none changed, or the thread lays out its rows again on every render. */
+    useThreadCards(scopeId: string, chatId: string): readonly ThreadCard[];
+    /* A header over every reply with its author and how long ago it began; null names the agent for a screen reader only. */
+    useReplyAuthor(scopeId: string, chatId: string): ReplyAuthor | null;
+}
+
+const NO_PROMPTS: readonly HostPrompt[] = [];
+const NO_CHATS: ReadonlyArray<{ id: string; title: string }> = [];
+const NO_ROWS: readonly number[] = [];
+const NO_FIND: TimelineFind = { open: false, bar: null, reveal: null, hitRows: NO_ROWS, currentRow: null };
+const NO_SOURCES: ReadonlyArray<{ title: string }> = [];
+const NO_URL: ResourceUrl = { url: null, failure: null };
+const NOWHERE: ChatPlace = { title: null, go: () => undefined };
+const NO_CARDS: readonly ThreadCard[] = [];
+
+const DEFAULT_HOST: ChatHost = {
+    accents: { all: [], featured: [], label: (id) => id, current: () => '' },
+    isApplePlatform,
+    isAppShortcut: () => false,
+    notify: () => undefined,
+    actions: null,
+    searchFiles: null,
+    attachments: { useUrl: () => NO_URL, read: () => Promise.reject(new Error('This app keeps no attached files')) },
+    ReadImage: null,
+    code: { useMode: () => 'light', useThemes: () => ({ light: 'github-light', dark: 'github-dark' }), custom: [] },
+    useStreaming: () => 'words',
+    fileLinks: null,
+    useTimelineFind: () => NO_FIND,
+    dictation: { Textarea: PlainTextarea, composer: null },
+    prompts: { useExtra: () => NO_PROMPTS, render: () => null, answer: () => Promise.reject(new Error('This app raises no prompts of its own')) },
+    useReferableChats: () => NO_CHATS,
+    openLogin: null,
+    useLoginBlocked: () => null,
+    useProjectLook: () => null,
+    useChatPlace: () => NOWHERE,
+    useContextSources: () => NO_SOURCES,
+    useHidesFolder: () => false,
+    useWelcome: () => false,
+    tasks: { useTasks: () => undefined, useTask: () => null },
+    confirm: { stopSubagents: (_scopeId, _chatId, run) => run(), stopTask: (_scopeId, _childId, _title, run) => run() },
+    fork: null,
+    openSettings: () => undefined,
+    useResumeAtReset: () => true,
+    useComposerPlaceholder: () => null,
+    ComposerSlot: null,
+    SubagentSlot: null,
+    useThreadCards: () => NO_CARDS,
+    useReplyAuthor: () => null
+};
+
+let host: ChatHost = DEFAULT_HOST;
+
+export function setChatHost(patch: Partial<ChatHost>): void {
+    if (patch.storage !== undefined) {
+        configureChatStorage(patch.storage);
+    }
+    host = { ...host, ...patch };
+}
+
+export function chatHost(): ChatHost {
+    return host;
+}

package/src/lazy.tsx

@@ -0,0 +1,64 @@
+import { lazy, type ComponentProps, type ComponentType } from 'react';
+
+type Loader = () => Promise<unknown>;
+
+const loaders: Loader[] = [];
+let register: ((load: Loader) => void) | null = null;
+const openErrorListeners = new Set<(error: unknown) => void>();
+
+/*
+ * Hands every module the chat loads lazily to the app's prefetcher: the ones made so far, and each
+ * one made from now on. Without it they load on their first render, as `React.lazy` does.
+ */
+export function setLazyPrefetch(next: (load: Loader) => void): void {
+    register = next;
+    for (const load of loaders) {
+        next(load);
+    }
+}
+
+/*
+ * Tells `listener` when a module the chat loads for a render fails to load, the way `onLazyOpenError`
+ * of `@adecore/ui` does for the app's own. A failed prefetch never reaches it.
+ */
+export function onLazyOpenError(listener: (error: unknown) => void): () => void {
+    openErrorListeners.add(listener);
+    return () => {
+        openErrorListeners.delete(listener);
+    };
+}
+
+/*
+ * `React.lazy` for a module that exports its component by name, `default` included. Once the module
+ * is here the component is drawn straight away, since `React.lazy` suspends for a tick even on a
+ * module the prefetcher already fetched.
+ */
+export function lazyNamed<Module extends Record<Name, ComponentType<any>>, Name extends keyof Module>(
+    load: () => Promise<Module>,
+    name: Name
+): ComponentType<ComponentProps<Module[Name]>> {
+    let loaded: ComponentType<any> | null = null;
+    const open = async (): Promise<ComponentType<any>> => {
+        const component = (await load())[name];
+        loaded ??= component;
+        return component;
+    };
+    loaders.push(open);
+    register?.(open);
+    // Only a render loads through here; a prefetch calls `open` itself, so its failures report nothing.
+    const Lazy = lazy(async () => {
+        try {
+            return { default: await open() };
+        } catch (error) {
+            for (const listener of openErrorListeners) {
+                listener(error);
+            }
+            throw error;
+        }
+    });
+    const LazyNamed = (props: ComponentProps<Module[Name]>) => {
+        const Component: ComponentType<any> = loaded ?? Lazy;
+        return <Component {...props} />;
+    };
+    return LazyNamed;
+}