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

package/src/state/providers.ts

@@ -0,0 +1,50 @@
+import { create } from 'zustand';
+import type { ProviderInfo } from '@adecore/agent-contracts';
+import { useChatScope } from '../scope';
+
+export interface ProvidersRow {
+    providers: ProviderInfo[];
+    loaded: boolean;
+}
+
+/* One object for a host that has not answered yet, so a selector gets a stable snapshot. */
+const NONE: ProvidersRow = { providers: [], loaded: false };
+
+interface ProvidersStore {
+    byScope: Record<string, ProvidersRow>;
+    setProviders(scopeId: string, providers: ProviderInfo[]): void;
+    forget(scopeId: string): void;
+}
+
+/* Which agent CLIs each host reports, and their models; filled once per connection. */
+export const useProvidersStore = create<ProvidersStore>((set, get) => ({
+    byScope: {},
+    setProviders(scopeId, providers) {
+        set({ byScope: { ...get().byScope, [scopeId]: { providers, loaded: true } } });
+    },
+    forget(scopeId) {
+        const { [scopeId]: _gone, ...rest } = get().byScope;
+        set({ byScope: rest });
+    }
+}));
+
+/*
+ * The CLIs of the host in scope. An agent menu has to offer what the host the chat will run on has
+ * installed, never what another host answered.
+ */
+export function useProviders<T>(select: (row: ProvidersRow) => T): T {
+    const { id } = useChatScope();
+    return useProvidersStore((s) => select(s.byScope[id] ?? NONE));
+}
+
+/* The same answer outside a render. */
+export function providersOf(scopeId: string): ProvidersRow {
+    return useProvidersStore.getState().byScope[scopeId] ?? NONE;
+}
+
+/* What one host's chat client fills in; it knows its own host and nothing of the others. */
+export function providerSinkFor(scopeId: string): { setProviders(providers: ProviderInfo[]): void } {
+    return {
+        setProviders: (providers) => useProvidersStore.getState().setProviders(scopeId, providers)
+    };
+}

package/src/state/usage.ts

@@ -0,0 +1,196 @@
+import type { UsageLimitsSnapshot, UsageSummaryPayload, UsageSummaryResult } from '@adecore/agent-contracts';
+import { chatStorageKey, chatStorageLegacyKeys, createChatStore, onChatStorageConfiguration } from '../storage';
+import { persistedJson } from '../chat/persisted-json';
+import { localTimeZone } from '@adecore/ui/format';
+import { useChatScope } from '../scope';
+import type { UsageCurrency } from '../usage/format';
+
+export type UsagePeriod = 'today' | '7d' | '30d' | '90d';
+export type UsageMetric = 'cost' | 'tokens';
+
+/* Only the id and the length. A store has no words, so the page names a period in its own language. */
+export const USAGE_PERIODS: readonly { id: UsagePeriod; days: number }[] = [
+    { id: 'today', days: 1 },
+    { id: '7d', days: 7 },
+    { id: '30d', days: 30 },
+    { id: '90d', days: 90 }
+];
+
+const storageKey = (): string => chatStorageKey('usage');
+
+export let USAGE_PREFERENCES_KEY = storageKey();
+onChatStorageConfiguration(() => {
+    USAGE_PREFERENCES_KEY = storageKey();
+});
+
+export function usagePreferencesKey(): string {
+    return storageKey();
+}
+
+interface Preferences {
+    period: UsagePeriod;
+    metric: UsageMetric;
+    /* Dollars until someone asks for euros; it is the viewer's setting, not the project's. */
+    currency: UsageCurrency;
+}
+
+const DEFAULTS: Preferences = { period: '7d', metric: 'cost', currency: 'USD' };
+
+function parsePreferences(raw: string | null): Preferences {
+    try {
+        const stored = JSON.parse(raw ?? '{}') as Partial<Preferences>;
+        return {
+            period: USAGE_PERIODS.some((period) => period.id === stored.period) ? stored.period! : DEFAULTS.period,
+            metric: stored.metric === 'tokens' || stored.metric === 'cost' ? stored.metric : DEFAULTS.metric,
+            currency: stored.currency === 'EUR' ? 'EUR' : DEFAULTS.currency
+        };
+    } catch {
+        return DEFAULTS;
+    }
+}
+
+const storage = persistedJson(storageKey, parsePreferences, DEFAULTS, () => chatStorageLegacyKeys('usage'));
+
+function readPreferences(): Preferences {
+    return storage.read();
+}
+
+function persist(preferences: Preferences): void {
+    storage.write(preferences);
+}
+
+/* The three stored choices out of the store, so a setter writes the other two back unchanged. */
+function chosen(state: Preferences): Preferences {
+    return { period: state.period, metric: state.metric, currency: state.currency };
+}
+
+function pad(value: number): string {
+    return String(value).padStart(2, '0');
+}
+
+/* The viewer's own calendar day; the host may stand in another zone and buckets in this one. */
+export function dayOf(date: Date): string {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/*
+ * What a period asks for. Today counts from local midnight in hours, the way the commit log already
+ * groups days, so every other period reads as one bar per calendar day.
+ */
+export function windowFor(period: UsagePeriod, now = new Date()): UsageSummaryPayload {
+    const days = USAGE_PERIODS.find((entry) => entry.id === period)?.days ?? 7;
+    const from = new Date(now.getFullYear(), now.getMonth(), now.getDate() - (days - 1));
+    return {
+        from: dayOf(from),
+        to: dayOf(now),
+        resolution: period === 'today' ? 'hour' : 'day',
+        timeZone: localTimeZone() ?? 'UTC'
+    };
+}
+
+/* A period, and only the usage of one account when one is picked; null is every account. */
+export function summaryPayload(period: UsagePeriod, account: string | null, now = new Date()): UsageSummaryPayload {
+    return account === null ? windowFor(period, now) : { ...windowFor(period, now), accounts: [account] };
+}
+
+/* What was asked, so an answer to the question before this one is never drawn over a newer one. */
+export function askedKey(payload: UsageSummaryPayload): string {
+    return `${payload.from}\0${payload.to}\0${payload.resolution}\0${payload.timeZone}\0${payload.accounts?.join(',') ?? ''}`;
+}
+
+/* The numbers of one host: its transcripts, priced by it. */
+interface UsageRow {
+    /* The question the summary on screen answers, or null while nothing has come back yet. */
+    asked: string | null;
+    summary: UsageSummaryResult | null;
+    /* True while the host has not answered the question that is being asked now. */
+    loading: boolean;
+    /* The last request failed; the summary before it stays on screen under a red line. */
+    failed: boolean;
+    limits: UsageLimitsSnapshot | null;
+}
+
+/* One object for a host nothing was read from yet, so a selector gets a stable snapshot. */
+const EMPTY: UsageRow = { asked: null, summary: null, loading: false, failed: false, limits: null };
+
+interface UsageStore extends Preferences {
+    byScope: Record<string, UsageRow>;
+    /*
+     * The host the usage page is showing, by scope id, or null for the one its surroundings are on.
+     * Deliberately not in `Preferences`, so it is not written to storage: a remembered host outlives
+     * this client's knowledge of it, and the numbers worth opening on are those of the host you work
+     * on. It does survive closing the page, which is what makes browsing two hosts bearable.
+     */
+    chosen: string | null;
+    /* Which host's numbers the page shows; null hands it back to the one around it. */
+    choose(scopeId: string | null): void;
+    setPeriod(period: UsagePeriod): void;
+    setMetric(metric: UsageMetric): void;
+    setCurrency(currency: UsageCurrency): void;
+    setLoading(scopeId: string, loading: boolean): void;
+    receive(scopeId: string, asked: string, summary: UsageSummaryResult): void;
+    fail(scopeId: string): void;
+    setLimits(scopeId: string, limits: UsageLimitsSnapshot): void;
+    /* A host that is forgotten takes its numbers with it; the three preferences are the viewer's and stay. */
+    forget(scopeId: string): void;
+}
+
+/* Reads the period, metric and currency again, once another window of the same origin wrote them. */
+export function reloadUsagePreferences(): void {
+    useUsageStore.setState(readPreferences());
+}
+
+export const useUsageStore = createChatStore<UsageStore>(
+    (set, get) => ({
+        ...DEFAULTS,
+        byScope: {},
+        chosen: null,
+        choose(scopeId) {
+            set({ chosen: scopeId });
+        },
+        setPeriod(period) {
+            persist({ ...chosen(get()), period });
+            set({ period });
+        },
+        setMetric(metric) {
+            persist({ ...chosen(get()), metric });
+            set({ metric });
+        },
+        setCurrency(currency) {
+            persist({ ...chosen(get()), currency });
+            set({ currency });
+        },
+        setLoading(scopeId, loading) {
+            set({ byScope: { ...get().byScope, [scopeId]: { ...(get().byScope[scopeId] ?? EMPTY), loading } } });
+        },
+        receive(scopeId, asked, summary) {
+            set({
+                byScope: { ...get().byScope, [scopeId]: { ...(get().byScope[scopeId] ?? EMPTY), asked, summary, loading: false, failed: false } }
+            });
+        },
+        fail(scopeId) {
+            set({ byScope: { ...get().byScope, [scopeId]: { ...(get().byScope[scopeId] ?? EMPTY), loading: false, failed: true } } });
+        },
+        setLimits(scopeId, limits) {
+            set({ byScope: { ...get().byScope, [scopeId]: { ...(get().byScope[scopeId] ?? EMPTY), limits } } });
+        },
+        forget(scopeId) {
+            const { [scopeId]: _gone, ...rest } = get().byScope;
+            set({ byScope: rest });
+        }
+    }),
+    (store) => store.setState(readPreferences())
+);
+
+/*
+ * The preferences of the viewer over the numbers of the host in scope, as one thing to select from.
+ * The usage page renders the host its picker is on as a scope of its own; everything outside it (the
+ * limit bars beside the work) reads the host around it, so browsing another host's spend never
+ * moves the bars that say how much of the plan the agents beside you have left.
+ */
+export type UsageView = Preferences & UsageRow;
+
+export function useUsage<T>(select: (view: UsageView) => T): T {
+    const { id } = useChatScope();
+    return useUsageStore((s) => select({ period: s.period, metric: s.metric, currency: s.currency, ...(s.byScope[id] ?? EMPTY) }));
+}

package/src/storage.ts

@@ -0,0 +1,113 @@
+import { create, type StateCreator, type StoreApi, type UseBoundStore } from 'zustand';
+
+export type ChatStorageRecord = 'drafts' | 'preferences' | 'stash' | 'usage';
+
+export interface ChatStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+export interface ChatStorageOptions {
+    namespace?: string;
+    keys?: Partial<Record<ChatStorageRecord, string>>;
+    legacyNamespaces?: readonly string[];
+    legacyKeys?: Partial<Record<ChatStorageRecord, readonly string[]>>;
+    /* Null keeps values in memory; an omitted adapter uses browser storage on first use. */
+    storage?: ChatStorageAdapter | null;
+}
+
+const SUFFIXES: Record<ChatStorageRecord, string> = {
+    drafts: 'chat.drafts',
+    preferences: 'chat.preferences',
+    stash: 'chat.stash',
+    usage: 'usage'
+};
+
+let options: ChatStorageOptions = {};
+let hydrated = false;
+const hydrators: Array<() => void> = [];
+const configurationListeners: Array<() => void> = [];
+
+export function onChatStorageConfiguration(listener: () => void): void {
+    configurationListeners.push(listener);
+}
+
+/* Configure once before using a store, so an imported component cannot read another host's records. */
+export function configureChatStorage(configuration: ChatStorageOptions): void {
+    if (hydrated) {
+        throw new Error('Configure chat storage before using chat stores');
+    }
+    options = {
+        ...configuration,
+        keys: { ...configuration.keys },
+        legacyNamespaces: [...(configuration.legacyNamespaces ?? [])],
+        legacyKeys: Object.fromEntries(Object.entries(configuration.legacyKeys ?? {}).map(([key, values]) => [key, [...values]]))
+    };
+    for (const listener of configurationListeners) {
+        listener();
+    }
+}
+
+export function chatStorageKey(record: ChatStorageRecord): string {
+    return options.keys?.[record] ?? `${options.namespace ?? 'adecore'}.${SUFFIXES[record]}`;
+}
+
+export function chatStorageLegacyKeys(record: ChatStorageRecord): readonly string[] {
+    return [...(options.legacyKeys?.[record] ?? []), ...(options.legacyNamespaces ?? []).map((namespace) => `${namespace}.${SUFFIXES[record]}`)];
+}
+
+export function chatStorageAdapter(): ChatStorageAdapter | null {
+    if (options.storage !== undefined) {
+        return options.storage;
+    }
+    try {
+        return globalThis.localStorage;
+    } catch {
+        return null;
+    }
+}
+
+export function hydrateChatStorage(): void {
+    if (hydrated) {
+        return;
+    }
+    hydrated = true;
+    for (const hydrate of hydrators) {
+        hydrate();
+    }
+}
+
+export function createChatStore<T>(initial: StateCreator<T>, hydrate: (store: StoreApi<T>) => void): UseBoundStore<StoreApi<T>> {
+    const store = create<T>(initial);
+    let initialized = false;
+    const hydrateOnce = (): void => {
+        if (initialized) {
+            return;
+        }
+        initialized = true;
+        hydrate(store);
+    };
+    hydrators.push(hydrateOnce);
+    const useStore = ((...args: Parameters<typeof store>) => {
+        hydrateChatStorage();
+        hydrateOnce();
+        return store(...args);
+    }) as typeof store;
+    Object.assign(useStore, store);
+    useStore.getState = () => {
+        hydrateChatStorage();
+        hydrateOnce();
+        return store.getState();
+    };
+    useStore.subscribe = (...args) => {
+        hydrateChatStorage();
+        hydrateOnce();
+        return store.subscribe(...args);
+    };
+    useStore.setState = ((...args: Parameters<typeof store.setState>) => {
+        hydrateChatStorage();
+        hydrateOnce();
+        store.setState(...args);
+    }) as typeof store.setState;
+    return useStore;
+}

package/src/theme.css

@@ -0,0 +1,212 @@
+/*
+ * The chat of @adecore/agents-react, its providers and its usage: the tokens only they read and the
+ * rules they draw with. Imported right after `@adecore/ui/theme.css`; the app scans the package with
+ * `@source` and loads `@tailwindcss/typography`, which the markdown of a thread builds on.
+ */
+:root, [data-theme="light"] {
+    /* Skills read as a second kind of token next to a file mention, so they get their own hue. */
+    --skill: #9333ea;
+    --skill-soft: #f7eeff;
+    /* One color per agent CLI, so a bar, a dot and a legend row all name the same provider. Apple's
+       system orange and teal; Gemini and Copilot are reserved for the day their transcripts are read. */
+    --chart-claude: #ff9500;
+    --chart-codex: #30b0c7;
+    --chart-gemini: #3b82f6;
+    --chart-copilot: #64748b;
+    /* What a chat's context holds, one color per part; the rest is the system's and stays gray. */
+    --chart-context-tools: #4d7ce6;
+    --chart-context-files: #9a63e0;
+    --chart-context-conversation: #2f9e5a;
+    --chart-context-system: var(--text-faint);
+    /* The current hit of a find, which has to stand out from the accent of a bookmark next to it. */
+    --chat-find: #facc15;
+}
+
+[data-theme="dark"] {
+    --skill: #c084fc;
+    --skill-soft: #2f2350;
+    --chart-claude: #ff9f0a;
+    --chart-codex: #40c8e0;
+    --chart-gemini: #60a5fa;
+    --chart-copilot: #94a3b8;
+    --chart-context-tools: #8aa7f5;
+    --chart-context-files: #b98af3;
+    --chart-context-conversation: #6dd08b;
+    --chart-context-system: var(--text-faint);
+    --chat-find: #f5c542;
+}
+
+/* Output and diffs take the terminal's colors when the app loads `@adecore/terminal/terminal.css`,
+   and the base theme's otherwise. Declared on every themed element, so a nested theme resolves its own. */
+:root, [data-theme] {
+    --chat-code-bg: var(--term-bg, var(--surface-sunken));
+    --chat-output: var(--term-fg, var(--text));
+    --chat-added: var(--term-ansi-green, var(--positive));
+    --chat-removed: var(--term-ansi-red, var(--status-error));
+}
+
+@theme inline {
+    --color-skill: var(--skill);
+    --color-skill-soft: var(--skill-soft);
+    --color-chart-claude: var(--chart-claude);
+    --color-chart-codex: var(--chart-codex);
+    --color-chart-gemini: var(--chart-gemini);
+    --color-chart-copilot: var(--chart-copilot);
+    --color-chart-context-tools: var(--chart-context-tools);
+    --color-chart-context-files: var(--chart-context-files);
+    --color-chart-context-conversation: var(--chart-context-conversation);
+    --color-chart-context-system: var(--chart-context-system);
+    --color-chat-find: var(--chat-find);
+    --color-chat-output: var(--chat-output);
+    --color-chat-added: var(--chat-added);
+    --color-chat-removed: var(--chat-removed);
+}
+
+@layer components {
+    /* ---------------------------------------------------------------- Chat */
+
+    /* Text in a chat is there to be read and copied, so the thread selects even though the app does
+       not. Its chrome stays out of it: a drag on a fold header or a chip would select the row.
+       The pretty wrap from `body` would be recomputed on the growing paragraph every frame a reply
+       streams, so the thread wraps the plain way.
+       The gaps are the air a thread needs to read as turns: the step from a question to its answer,
+       and the wider step from the end of one turn to the next question. A view of its own gets more
+       of both, the way its type does. The block gap is the step inside a turn, where a run of tool
+       lines meets prose or a card. */
+    .chat-thread { user-select: text; text-wrap-style: auto; --chat-answer-gap: 16px; --chat-turn-gap: 24px; --chat-block-gap: 12px; }
+    .chat-column .chat-thread { --chat-answer-gap: 20px; --chat-turn-gap: 32px; --chat-block-gap: 16px; }
+    .chat-thread button, .chat-thread kbd { user-select: none; }
+
+    /*
+     * A chat that is a view of its own reads in a column. The scroller keeps the full width of the
+     * main column, so its scrollbar sits at that column's right edge and nothing jumps when the
+     * thread grows past a screenful; only the rows and the composer inside it are centered.
+     */
+    .chat-column .chat-column-content { margin-inline: auto; max-width: 768px; }
+    /* Wider by the input's inset (`.composer-input .cm-content` padding plus the card's border), so what is typed lines up with the thread. */
+    .chat-column .chat-composer-content { margin-inline: auto; max-width: calc(768px + 2 * 21px); }
+
+    /* A diff inside a chat tool block; the library paints its own colors inside a shadow root and
+       takes the face it draws them in through these variables. */
+    .chat-diff { font-size: var(--text-code); --diffs-font-size: var(--text-code); --diffs-font-family: var(--font-mono); }
+    .chat-diff + .chat-diff { border-top: 1px solid var(--border); }
+
+    /* Live tool rows shine once across; a paused animation costs nothing. */
+    .chat-live-text {
+        background: linear-gradient(90deg, var(--text-muted) 0%, var(--text) 50%, var(--text-muted) 100%);
+        background-size: 200% 100%;
+        -webkit-background-clip: text;
+        background-clip: text;
+        color: transparent;
+        animation: chat-shine 1.6s linear infinite;
+    }
+    @keyframes chat-shine { from { background-position: 200% 0; } to { background-position: -200% 0; } }
+
+    /* A word of a reply that just arrived. The duration is REVEAL_FADE_MS in chat/ui/reveal.ts, which
+       keeps the spans until it is over; ease-in-out, because ease-out jumps up and then trails. */
+    .chat-fade { animation: chat-fade 300ms ease-in-out both; }
+    /* A whole reply that was written out of sight. */
+    .chat-fade-whole { animation: chat-fade 220ms ease-out both; }
+    /* A block of a reply streamed a block at a time, faded in when it is inserted and never when a
+       finished thread opens, which carries no `data-arriving`. */
+    .chat-markdown[data-arriving] > * {
+        transition: opacity 300ms ease-in-out;
+        @starting-style { opacity: 0; }
+    }
+    @keyframes chat-fade { from { opacity: 0; } to { opacity: 1; } }
+
+    /* The row a jump from outside the chat (the card of a change in a file) landed on. */
+    .chat-flash { animation: chat-flash 1600ms ease-out both; }
+    @keyframes chat-flash {
+        from { background: color-mix(in srgb, var(--accent) 18%, transparent); }
+        to { background: transparent; }
+    }
+}
+
+/*
+ * Markdown, outside every layer on purpose. The typography plugin registers `.prose` as a utility,
+ * and a later layer beats an earlier one whatever the specificity, so a rule that has to outrank
+ * prose cannot live in `components`. Unlayered styles win over every layer, which is the one
+ * place the app's tokens and scale are sure to land on top of the plugin's.
+ */
+/*
+ * Markdown anywhere in the app: the chat timeline, a note node and the file preview all render
+ * the same `Markdown` component, which carries `prose prose-sm max-w-none text-sm` next to this
+ * class. Prose brings the rhythm; everything here is what the app decides instead of the plugin.
+ * The semantic tokens flip with the theme on their own, so the prose variables read from them
+ * and `prose-invert` is a second source of truth the app does not need. The size comes from the
+ * `text-sm` utility, which a node, a view and the file preview each move.
+ */
+.prose.chat-markdown {
+    --tw-prose-body: var(--text);
+    --tw-prose-headings: var(--text);
+    --tw-prose-lead: var(--text-muted);
+    --tw-prose-links: var(--accent);
+    --tw-prose-bold: var(--text);
+    --tw-prose-counters: var(--text-faint);
+    --tw-prose-bullets: var(--text-faint);
+    --tw-prose-hr: var(--border);
+    --tw-prose-quotes: var(--text);
+    --tw-prose-quote-borders: var(--border);
+    --tw-prose-captions: var(--text-muted);
+    --tw-prose-kbd: var(--text);
+    --tw-prose-code: var(--text);
+    --tw-prose-pre-code: var(--text);
+    --tw-prose-pre-bg: var(--surface-sunken);
+    --tw-prose-th-borders: var(--border);
+    --tw-prose-td-borders: var(--border);
+}
+/* Headings stay on the app's scale, which is flatter than the one prose brings. */
+.chat-markdown :is(h1, h2, h3, h4) { font-weight: 600; line-height: round(1.3em, 1px); }
+.chat-markdown h1 { font-size: var(--text-lg); }
+.chat-markdown h2 { font-size: var(--text-base); }
+.chat-markdown :is(h3, h4) { font-size: var(--text-sm); }
+.chat-markdown a { text-underline-offset: 2px; }
+/* Code is the app's own: `--text-code` at every depth, and none of the quotes prose puts around
+   inline code, since the chip the component draws already says what it is. */
+.chat-markdown code { font-size: var(--text-code); font-weight: 400; }
+.chat-markdown code::before, .chat-markdown code::after { content: none; }
+/* A checked box is the marker; prose would put a bullet next to it. */
+.chat-markdown li:has(> input[type="checkbox"]) { list-style: none; }
+.chat-markdown input[type="checkbox"] { margin-right: 6px; accent-color: var(--accent); }
+/* A wide table scrolls in its own wrapper instead of stretching the column it sits in. The
+   wrapper is a scroll container, so the air around the table has to sit on it, not inside it. */
+.chat-table { overflow-x: auto; margin-block: 2em; }
+.chat-markdown table { margin: 0; border-collapse: collapse; font-size: var(--text-xs); }
+.chat-markdown :is(th, td) { border: 1px solid var(--tw-prose-td-borders); padding: 4px 8px; text-align: left; }
+
+/* A code block is shiki's own `<pre>`, which brings a background of its own to override. */
+.chat-code { border-radius: 8px; border: 1px solid var(--border); background: var(--chat-code-bg); overflow: auto; }
+.chat-code pre { margin: 0; padding: round(0.625rem, 1px) round(0.75rem, 1px); background: transparent !important; font-family: var(--font-mono); font-size: var(--text-code); line-height: var(--text-code--line-height); }
+.chat-code code { font-family: inherit; }
+
+/* The chat composer is a CodeMirror editor, whose base theme lands in an unlayered style tag at
+   mount. These rules stay unlayered too, and carry one class more than the theme's selectors. */
+.composer-input .cm-editor { max-height: 200px; }
+.composer-input .cm-editor.cm-focused { outline: none; }
+.composer-input .cm-editor .cm-scroller { overflow: auto; font-family: inherit; line-height: inherit; }
+.composer-input .cm-editor .cm-scroller .cm-content { padding: 18px 14px 6px 20px; caret-color: var(--text); }
+.composer-input .cm-scroller .cm-content .cm-line { padding: 0; }
+.composer-input .cm-scroller .cm-content .cm-placeholder { color: var(--text-faint); }
+.composer-hints, .composer-hints-extra { display: inline-flex; align-items: center; gap: 8px; white-space: nowrap; }
+/* The joiner starts with its own comma, so it sits against the lead without the gap. */
+.composer-hints-extra { margin-left: -8px; }
+.composer-hints kbd { padding: 0 6px; border-radius: 5px; background: var(--surface-active); color: var(--text-muted); font-family: var(--font-mono); font-size: var(--text-code); line-height: var(--text-code--line-height); }
+/* The widths of Tailwind's `@md` container variant, which the rest of the composer narrows at. */
+@container composer (width < 28rem) {
+    .composer-input .cm-editor .cm-scroller .cm-content { padding: 14px 12px 4px 14px; }
+}
+/* The hints stay on the line of the lead or go; wrapped, they would start left of the text. */
+@container composer (width < 36rem) {
+    .composer-hints-extra { display: none; }
+}
+/* Markdown stays source while you type: the markers stay put and dim, and what they wrap takes its look. */
+.composer-input .cm-md-mark { color: var(--text-faint); }
+.composer-input .cm-md-strong, .composer-input .cm-md-heading { font-weight: 600; }
+.composer-input .cm-md-emphasis { font-style: italic; }
+.composer-input .cm-md-strike { text-decoration: line-through; }
+.composer-input .cm-md-link { color: var(--accent); text-decoration: underline; }
+.composer-input .cm-md-code { padding: 1px 2px; border-radius: 4px; background: var(--surface-sunken); font-family: var(--font-mono); font-size: var(--text-code); }
+.composer-input .cm-content .cm-line.cm-md-fence { padding: 0 8px; background: var(--surface-sunken); font-family: var(--font-mono); font-size: var(--text-code); }
+.composer-input .cm-content .cm-line.cm-md-fence-start { padding-top: 4px; border-top-left-radius: 6px; border-top-right-radius: 6px; }
+.composer-input .cm-content .cm-line.cm-md-fence-end { padding-bottom: 4px; border-bottom-left-radius: 6px; border-bottom-right-radius: 6px; }

package/src/transport.ts

@@ -0,0 +1,50 @@
+import type { z } from 'zod';
+import type { AGENT_EVENT_SCHEMAS, AGENT_REQUEST_SCHEMAS, AgentEventType, AgentRequestType } from '@adecore/agent-contracts/protocol';
+
+export type ChatRequestMap = {
+    [T in AgentRequestType]: {
+        payload: z.infer<(typeof AGENT_REQUEST_SCHEMAS)[T]['payload']>;
+        result: z.infer<(typeof AGENT_REQUEST_SCHEMAS)[T]['result']>;
+    };
+};
+
+export type ChatEventMap = {
+    [E in AgentEventType]: z.infer<(typeof AGENT_EVENT_SCHEMAS)[E]>;
+};
+
+export type ChatTransportStatus = 'connecting' | 'open' | 'closed';
+
+/*
+ * What the chat, its providers and their usage need of whatever runs the chats: a request with its
+ * typed answer, the events, and whether the link is up. A link that comes back is a fresh one to the
+ * host, so everything that holds state there says it again when the status turns `open`. An app that
+ * talks to several hosts has one of these per host; nothing here assumes there is only one.
+ */
+export interface ChatTransport {
+    request<T extends AgentRequestType>(type: T, payload: ChatRequestMap[T]['payload']): Promise<ChatRequestMap[T]['result']>;
+    on<E extends AgentEventType>(event: E, handler: (payload: ChatEventMap[E]) => void): () => void;
+    readonly status: ChatTransportStatus;
+    subscribeStatus(handler: (status: ChatTransportStatus) => void): () => void;
+}
+
+/* A refused request always carries a code, so a caller branches on it instead of on the message. */
+export class ChatTransportError extends Error {
+    readonly code: string;
+
+    constructor(code: string, message: string) {
+        super(message);
+        this.name = 'ChatTransportError';
+        this.code = code;
+    }
+}
+
+/* The code of a refusal from any transport, this package's or the app's own: every one of them carries it the same way. */
+export function errorCode(error: unknown): string | null {
+    return typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string' ? error.code : null;
+}
+
+/* Whether a request failed because the link was down rather than because the host refused it; the reconnect asks again. */
+export function isConnectionError(error: unknown): boolean {
+    const code = errorCode(error);
+    return code === 'not-connected' || code === 'disconnected';
+}

package/src/ui/PlainTextarea.tsx

@@ -0,0 +1,6 @@
+import type { TextareaProps } from '../host';
+
+/* The field a written answer goes in when the app brings no dictation of its own. */
+export function PlainTextarea({ buttonClassName: _buttonClassName, ...props }: TextareaProps) {
+    return <textarea {...props} />;
+}