@adecore/agents-react 0.31.0 → 0.31.1

package/dist/host.d.ts

@@ -3,7 +3,7 @@ import type { Extension } from '@codemirror/state';
 import type { EditorView } from '@codemirror/view';
 import type { Highlighter, ThemeRegistration } from 'shiki';
 import type { EditorEngine } from '@adecore/editor';
-import type { AgentKind, ChatCheckpointDiff, ChatConfigurePayload, ChatGoalAction, ChatItem, ChatSubagentItem, ChatUiChoicePayload, ChatUiQueryPayload, ChatUiQueryReading, ChatUiLinkPayload, ChatUiLinkReading } from '@adecore/agent-contracts';
+import type { AgentKind, ChatCheckpointDiff, ChatConfigurePayload, ChatGoalAction, ChatItem, ChatSubagentItem, ChatUiChoicePayload, ChatUiQueryPayload, ChatUiQueryReading, ChatUiLinkPayload, ChatUiLinkReading, ProviderPlatform } from '@adecore/agent-contracts';
 import type { TimelineRow } from './chat/logic/timeline.js';
 import type { FindReveal } from './chat/ui/find-reveal.js';
 import type { PromptAction } from './prompts/logic/prompts.js';
@@ -249,6 +249,9 @@ export interface ChatHost {
     }>;
     openLogin: ((scopeId: string, kind: AgentKind, accountId: string, name: string) => Promise<void>) | null;
     useLoginBlocked(scopeId: string): string | null;
+    runProviderCommand?(scopeId: string, kind: AgentKind, command: string): void;
+    useMachinePlatform?(scopeId: string): ProviderPlatform | null;
+    providerKeyNote?(variable: string): string | null;
     useProjectLook(scopeId: string, projectId: string | null): {
         name: string;
         mark: ReactNode;

package/dist/locales/en/agent-providers.d.ts

@@ -22,6 +22,43 @@ declare const _default: {
         none: string;
         noAccounts: string;
     };
+    install: {
+        notInstalled: string;
+        steps: string;
+        platform: string;
+        platforms: {
+            darwin: string;
+            linux: string;
+            win32: string;
+        };
+        copy: string;
+        copied: string;
+        run: string;
+        guide: string;
+        install: {
+            title: string;
+            none: string;
+            done: string;
+            doneNoVersion: string;
+        };
+        signIn: {
+            title: string;
+            command: string;
+            env: string;
+            chat: string;
+            or: string;
+            unknown: string;
+        };
+        start: {
+            title: string;
+            description: string;
+        };
+        footer: {
+            missing: string;
+            found: string;
+        };
+        fallback: string;
+    };
     abilities: {
         version: string;
         chatAndTerminal: string;

package/dist/locales/en/agent-providers.js

@@ -18,10 +18,47 @@ export default {
         addAccount: 'Add a {{provider}} account',
         notInstalled: 'Not installed',
         missing: 'Missing',
-        notInstalledNote: 'To add one, install it and restart Ruimte on that machine.',
+        notInstalledNote: 'Install one on this machine to use it here.',
         none: 'No agent CLIs found on this machine.',
         noAccounts: 'This machine keeps no accounts yet. Update Ruimte there to add one.'
     },
+    install: {
+        notInstalled: 'Not installed',
+        steps: 'Steps to set up {{provider}}',
+        platform: 'System',
+        platforms: {
+            darwin: 'macOS',
+            linux: 'Linux',
+            win32: 'Windows'
+        },
+        copy: 'Copy',
+        copied: 'Copied',
+        run: 'Run in a terminal',
+        guide: 'Install guide',
+        install: {
+            title: 'Install the CLI',
+            none: 'There is no install command for this system.',
+            done: 'Installed, version {{version}}.',
+            doneNoVersion: 'Installed.'
+        },
+        signIn: {
+            title: 'Sign in',
+            command: 'Run this in a terminal and follow its steps:',
+            env: 'Set <code>{{variable}}</code> in the environment the CLI starts in.',
+            chat: 'The first chat asks you to sign in.',
+            or: 'Or',
+            unknown: 'The CLI asks you to sign in the first time it runs.'
+        },
+        start: {
+            title: 'Start working',
+            description: 'Pick {{provider}} for your next chat or terminal.'
+        },
+        footer: {
+            missing: 'Not found on this machine yet. It is checked again when you come back to this window.',
+            found: 'Found on this machine.'
+        },
+        fallback: 'Install {{provider}} on this machine to use it here.'
+    },
     abilities: {
         version: 'Version {{version}}.',
         chatAndTerminal: 'Chat and terminal.',

package/dist/locales/nl/agent-providers.d.ts

@@ -22,6 +22,43 @@ declare const _default: {
         none: string;
         noAccounts: string;
     };
+    install: {
+        notInstalled: string;
+        steps: string;
+        platform: string;
+        platforms: {
+            darwin: string;
+            linux: string;
+            win32: string;
+        };
+        copy: string;
+        copied: string;
+        run: string;
+        guide: string;
+        install: {
+            title: string;
+            none: string;
+            done: string;
+            doneNoVersion: string;
+        };
+        signIn: {
+            title: string;
+            command: string;
+            env: string;
+            chat: string;
+            or: string;
+            unknown: string;
+        };
+        start: {
+            title: string;
+            description: string;
+        };
+        footer: {
+            missing: string;
+            found: string;
+        };
+        fallback: string;
+    };
     abilities: {
         version: string;
         chatAndTerminal: string;

package/dist/locales/nl/agent-providers.js

@@ -18,10 +18,47 @@ export default {
         addAccount: 'Een {{provider}}-account toevoegen',
         notInstalled: 'Niet geïnstalleerd',
         missing: 'Ontbreekt',
-        notInstalledNote: 'Installeer er een en start Ruimte op die machine opnieuw om hem toe te voegen.',
+        notInstalledNote: 'Installeer er een op deze machine om hem hier te gebruiken.',
         none: "Geen agent-CLI's gevonden op deze machine.",
         noAccounts: 'Deze machine houdt nog geen accounts bij. Werk Ruimte daar bij om er een toe te voegen.'
     },
+    install: {
+        notInstalled: 'Niet geïnstalleerd',
+        steps: '{{provider}} instellen in stappen',
+        platform: 'Systeem',
+        platforms: {
+            darwin: 'macOS',
+            linux: 'Linux',
+            win32: 'Windows'
+        },
+        copy: 'Kopiëren',
+        copied: 'Gekopieerd',
+        run: 'In een terminal uitvoeren',
+        guide: 'Installatiegids',
+        install: {
+            title: 'Installeer de CLI',
+            none: 'Er is geen installatiecommando voor dit systeem.',
+            done: 'Geïnstalleerd, versie {{version}}.',
+            doneNoVersion: 'Geïnstalleerd.'
+        },
+        signIn: {
+            title: 'Log in',
+            command: 'Voer dit uit in een terminal en volg de stappen:',
+            env: 'Zet <code>{{variable}}</code> in de omgeving waarin de CLI start.',
+            chat: 'De eerste chat vraagt je om in te loggen.',
+            or: 'Of',
+            unknown: 'De CLI vraagt je om in te loggen als hij voor het eerst draait.'
+        },
+        start: {
+            title: 'Aan de slag',
+            description: 'Kies {{provider}} voor je volgende chat of terminal.'
+        },
+        footer: {
+            missing: 'Nog niet gevonden op deze machine. Er wordt opnieuw gekeken als je terugkomt in dit venster.',
+            found: 'Gevonden op deze machine.'
+        },
+        fallback: 'Installeer {{provider}} op deze machine om hem hier te gebruiken.'
+    },
     abilities: {
         version: 'Versie {{version}}.',
         chatAndTerminal: 'Chat en terminal.',

package/dist/providers/InstallPage.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderInfo } from '@adecore/agent-contracts';
+import { type ProviderInstallStep } from './install-steps.js';
+interface InstallPageProps {
+    provider: ProviderInfo;
+    signedIn: boolean;
+    extra: ProviderInstallStep | null;
+}
+export declare function InstallPage({ provider, signedIn, extra }: InstallPageProps): import("react").JSX.Element;
+export {};

package/dist/providers/InstallPage.js

@@ -0,0 +1,74 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import clsx from 'clsx';
+import { Trans, useTranslation } from 'react-i18next';
+import { Check, Copy, ExternalLink, SquareTerminal } from 'lucide-react';
+import { Button, copyText, Icon, Pill, Segmented } from '@adecore/ui';
+import { useChatHost } from '../host.js';
+import { useChatScope } from '../scope.js';
+import { installPlatforms, installStepStates, pagePlatform } from './install-steps.js';
+import { CliMark } from './parts.js';
+const noPlatform = () => null;
+function CommandBlock({ command }) {
+    const { t } = useTranslation('agent-providers');
+    const [copied, setCopied] = useState(null);
+    return (_jsxs("div", { className: "flex min-w-0 items-center gap-2 rounded-lg border border-border bg-surface-sunken py-1 pr-1 pl-3", children: [_jsx("code", { className: "min-w-0 grow font-mono text-code break-all text-text select-text", children: command }), _jsxs(Button, { size: "xs", onClick: () => {
+                    copyText(command);
+                    setCopied(command);
+                }, children: [_jsx(Icon, { icon: copied === command ? Check : Copy, size: 12 }), copied === command ? t('install.copied') : t('install.copy')] })] }));
+}
+function Step({ index, state, title, children }) {
+    return (_jsxs("li", { "aria-current": state === 'current' ? 'step' : undefined, "data-state": state, className: clsx('flex min-w-0 gap-3 rounded-xl border p-4', state === 'current' ? 'border-accent' : 'border-border'), children: [_jsx("span", { className: clsx('grid size-6 shrink-0 place-items-center rounded-full text-xs font-medium', state === 'done' && 'bg-positive text-positive-text', state === 'current' && 'border border-accent text-accent', state === 'later' && 'bg-text/7 text-text-faint'), children: state === 'done' ? _jsx(Icon, { icon: Check, size: 14 }) : index + 1 }), _jsxs("div", { className: "flex min-w-0 grow flex-col gap-3", children: [_jsx("h4", { className: clsx('text-sm leading-6 font-medium', state === 'later' ? 'text-text-muted' : 'text-text'), children: title }), children] })] }));
+}
+function SignInWay({ way, canRun, onRun }) {
+    const { t } = useTranslation('agent-providers');
+    const { providerKeyNote } = useChatHost();
+    switch (way.kind) {
+        case 'command':
+            return (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx("p", { className: "text-xs text-text-muted", children: t('install.signIn.command') }), _jsx(CommandBlock, { command: way.command }), canRun && (_jsxs(Button, { variant: "secondary", size: "sm", className: "self-start", onClick: () => onRun(way.command), children: [_jsx(Icon, { icon: SquareTerminal, size: 14 }), t('install.run')] }))] }));
+        case 'env': {
+            const note = providerKeyNote?.(way.variable) ?? null;
+            return (_jsxs("p", { className: "text-xs text-text-muted", children: [_jsx(Trans, { t: t, i18nKey: "install.signIn.env", values: { variable: way.variable }, components: { code: _jsx("code", { className: "font-mono text-code text-text" }) } }), note !== null && ` ${note}`] }));
+        }
+        case 'chat':
+            return _jsx("p", { className: "text-xs text-text-muted", children: t('install.signIn.chat') });
+    }
+}
+/* How to get a CLI that is not on the machine yet, step by step, until it is there and signed in. */
+export function InstallPage({ provider, signedIn, extra }) {
+    const { t } = useTranslation('agent-providers');
+    const { id: scopeId } = useChatScope();
+    const host = useChatHost();
+    const useMachinePlatform = host.useMachinePlatform ?? noPlatform;
+    const machine = useMachinePlatform(scopeId) ?? pagePlatform();
+    const { offered, initial } = installPlatforms(provider, machine);
+    // Only a person's pick is kept, so a machine whose system arrives late still opens on its own.
+    const [chosen, setPlatform] = useState(null);
+    const platform = chosen ?? initial;
+    const install = provider.install;
+    const run = host.runProviderCommand;
+    const onRun = (command) => run?.(scopeId, provider.kind, command);
+    const command = platform === null ? undefined : install?.commands[platform];
+    const steps = [];
+    steps.push({
+        title: t('install.install.title'),
+        done: provider.installed,
+        body: provider.installed ? (_jsx("p", { className: "text-xs text-text-muted", children: provider.version ? t('install.install.done', { version: provider.version }) : t('install.install.doneNoVersion') })) : (_jsxs(_Fragment, { children: [offered.length > 1 && platform !== null && (_jsx(Segmented, { value: platform, label: t('install.platform'), options: offered.map((id) => ({ id, label: t(`install.platforms.${id}`) })), onValueChange: setPlatform })), command ? _jsx(CommandBlock, { command: command }) : _jsx("p", { className: "text-xs text-text-muted", children: t('install.install.none') }), ((command && run) || install?.guideUrl) && (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [command && run && (_jsxs(Button, { variant: "primary", onClick: () => onRun(command), children: [_jsx(Icon, { icon: SquareTerminal, size: 14 }), t('install.run')] })), install?.guideUrl && (_jsxs(Button, { href: install.guideUrl, children: [t('install.guide'), _jsx(Icon, { icon: ExternalLink, size: 14 })] }))] }))] }))
+    });
+    if (extra !== null) {
+        steps.push(extra);
+    }
+    const ways = install?.signIn ?? [];
+    steps.push({
+        title: t('install.signIn.title'),
+        done: provider.installed && signedIn,
+        body: ways.length === 0 ? (_jsx("p", { className: "text-xs text-text-muted", children: t('install.signIn.unknown') })) : (ways.map((way, index) => (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [index > 0 && _jsx("span", { className: "text-xs font-medium text-text-faint", children: t('install.signIn.or') }), _jsx(SignInWay, { way: way, canRun: run !== undefined && provider.installed, onRun: onRun })] }, `${way.kind}-${index}`))))
+    });
+    steps.push({
+        title: t('install.start.title'),
+        done: false,
+        body: _jsx("p", { className: "text-xs text-text-muted", children: t('install.start.description', { provider: provider.name }) })
+    });
+    const states = installStepStates(steps.map((step) => step.done));
+    return (_jsxs(_Fragment, { children: [_jsxs("header", { className: "flex min-w-0 items-start gap-3", children: [_jsx("span", { className: "grid size-10 shrink-0 place-items-center rounded-xl bg-surface-sunken", children: _jsx(CliMark, { kind: provider.kind, size: 20 }) }), _jsxs("div", { className: "flex min-w-0 grow flex-col", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("h3", { className: "truncate text-lg font-semibold text-text", children: provider.name }), provider.installed ? (provider.version && (_jsx(Pill, { tone: "idle", mono: true, children: provider.version }))) : (_jsx(Pill, { children: t('install.notInstalled') }))] }), install && _jsx("p", { className: "text-xs text-text-muted", children: install.description })] })] }), install ? (_jsx("ol", { "aria-label": t('install.steps', { provider: provider.name }), className: "flex min-w-0 flex-col gap-3", children: steps.map((step, index) => (_jsx(Step, { index: index, state: states[index], title: step.title, children: step.body }, index))) })) : (_jsx("p", { className: "text-xs text-text-muted", children: t('install.fallback', { provider: provider.name }) })), _jsxs("p", { className: "flex min-w-0 items-center gap-2 text-xs text-text-muted", children: [_jsx("span", { "aria-hidden": true, className: clsx('size-2 shrink-0 rounded-full', provider.installed ? 'bg-status-idle' : 'bg-text-faint') }), provider.installed ? t('install.footer.found') : t('install.footer.missing')] })] }));
+}

package/dist/providers/ProvidersPane.d.ts

@@ -1,9 +1,11 @@
 import { type ReactNode } from 'react';
 import type { ProviderInfo } from '@adecore/agent-contracts';
+import type { ProviderInstallStep } from './install-steps.js';
 interface ProvidersPaneProps {
     target?: string | null;
     detailOf?(provider: ProviderInfo): ReactNode | null;
     defaults?: boolean;
+    installStepOf?(provider: ProviderInfo): ProviderInstallStep | null;
 }
-export declare function ProvidersPane({ target, detailOf, defaults }: ProvidersPaneProps): import("react").JSX.Element;
+export declare function ProvidersPane({ target, detailOf, defaults, installStepOf }: ProvidersPaneProps): import("react").JSX.Element;
 export {};

package/dist/providers/ProvidersPane.js

@@ -2,16 +2,17 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useMemo, useState } from 'react';
 import clsx from 'clsx';
 import { useTranslation } from 'react-i18next';
-import { Plus, Terminal } from 'lucide-react';
+import { Plus } from 'lucide-react';
 import { AccountDot } from '../agents/AccountDot.js';
 import { ACCOUNT_TONE_CLASSES, accountLoginOf, accountName, accountsOfKind, accountStatusLine } from '../agents/accounts.js';
-import { ErrorBoundary, Icon, IconButton, SectionLabel, Skeleton } from '@adecore/ui';
+import { ErrorBoundary, IconButton, SectionLabel, Skeleton } from '@adecore/ui';
 import { MasterDetail } from '@adecore/ui/settings';
 import { useChatHost } from '../host.js';
 import { useChatScope } from '../scope.js';
 import { AccountDetail } from './AccountDetail.js';
 import { AddAccountForm } from './AddAccountForm.js';
 import { CliDetail } from './CliDetail.js';
+import { InstallPage } from './InstallPage.js';
 import { CliMark } from './parts.js';
 import { useProviderAccounts } from '../state/provider-accounts.js';
 import { useProviders } from '../state/providers.js';
@@ -20,7 +21,7 @@ function ListRow({ selected, onSelect, children, trailing, className }) {
     return (_jsxs("div", { className: clsx('flex min-w-0 shrink-0 items-center gap-2 rounded-lg pr-2', selected ? 'bg-text/5' : 'hover:bg-surface-hover', className), children: [_jsx("button", { type: "button", "aria-current": selected ? 'true' : undefined, className: "flex min-w-0 grow items-center gap-3 self-stretch rounded-lg py-2 pl-3 text-left focus-visible:-outline-offset-2", onClick: onSelect, children: children }), trailing] }));
 }
 /* The agent CLIs of the host in scope, each with its accounts, beside the detail of what is picked. */
-export function ProvidersPane({ target = null, detailOf, defaults = true }) {
+export function ProvidersPane({ target = null, detailOf, defaults = true, installStepOf }) {
     const { t } = useTranslation('agent-providers');
     const { id: scopeId } = useChatScope();
     const providers = useProviders((s) => s.providers);
@@ -40,7 +41,8 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }) {
     const current = picked !== null && (picked.kind !== 'account' || pickedEntry !== null) ? picked : installed[0] ? { kind: 'cli', cli: installed[0].kind } : null;
     const currentAccount = current?.kind === 'account' ? accounts?.accounts[current.id] : undefined;
     const currentCli = current === null ? null : current.kind === 'account' ? currentAccount?.kind : current.cli;
-    const provider = installed.find((entry) => entry.kind === currentCli) ?? null;
+    const provider = (current?.kind === 'install' ? providers : installed).find((entry) => entry.kind === currentCli) ?? null;
+    const picksCli = (kind) => (current?.kind === 'cli' || current?.kind === 'install') && current.cli === kind;
     // A search result lands on a row of a CLI's detail, so a picked account makes way for its CLI.
     const [seenTarget, setSeenTarget] = useState(target);
     if (target !== seenTarget) {
@@ -60,18 +62,27 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }) {
     };
     const group = (cli) => {
         const entries = cli.installed ? entriesOf(cli.kind) : [];
-        return (_jsxs("div", { className: "flex min-w-0 shrink-0 flex-col gap-0.5 pt-1", children: [_jsxs(ListRow, { selected: current?.kind === 'cli' && current.cli === cli.kind, onSelect: () => setPicked({ kind: 'cli', cli: cli.kind }), className: "pr-1", trailing: loginOf(cli.kind) !== null && (_jsx(IconButton, { icon: Plus, size: "sm", label: t('list.addAccount', { provider: cli.name }), onClick: () => setPicked({ kind: 'add', cli: cli.kind }) })), children: [_jsx(CliMark, { kind: cli.kind }), _jsx("span", { className: "min-w-0 grow truncate text-xs font-medium text-text", children: cli.name }), cli.capabilities.terminal && cli.version && _jsx("span", { className: "shrink-0 font-mono text-code text-text-faint", children: cli.version })] }), entries.map((entry) => {
+        return (_jsxs("div", { className: "flex min-w-0 shrink-0 flex-col gap-0.5 pt-1", children: [_jsxs(ListRow, { selected: picksCli(cli.kind), onSelect: () => setPicked({ kind: 'cli', cli: cli.kind }), className: "pr-1", trailing: loginOf(cli.kind) !== null && (_jsx(IconButton, { icon: Plus, size: "sm", label: t('list.addAccount', { provider: cli.name }), onClick: () => setPicked({ kind: 'add', cli: cli.kind }) })), children: [_jsx(CliMark, { kind: cli.kind }), _jsx("span", { className: "min-w-0 grow truncate text-xs font-medium text-text", children: cli.name }), cli.capabilities.terminal && cli.version && _jsx("span", { className: "shrink-0 font-mono text-code text-text-faint", children: cli.version })] }), entries.map((entry) => {
                     const name = accountName(entry, cli.name);
                     const status = accountStatusLine(entry.status, loginOf(cli.kind) === 'terminal');
                     return (_jsxs(ListRow, { selected: current?.kind === 'account' && current.id === entry.id, onSelect: () => setPicked({ kind: 'account', id: entry.id }), children: [_jsx("span", { className: "grid w-3.5 shrink-0 place-items-center", children: _jsx(AccountDot, { color: entry.account.color, className: "size-2.25" }) }), _jsxs("span", { className: "flex min-w-0 grow flex-col", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-2 text-sm text-text", children: [_jsx("span", { className: "truncate", children: name }), entry.isDefault && (_jsx("span", { className: "shrink-0 rounded-md bg-surface-active px-1.5 text-xs text-text-muted", children: t('list.default') }))] }), _jsx("span", { className: clsx('truncate text-xs', ACCOUNT_TONE_CLASSES[status.tone]), children: status.text })] })] }, entry.id));
                 })] }, cli.kind));
     };
-    const list = !loaded ? (_jsxs("div", { className: "flex flex-col gap-3 p-3", children: [_jsx(Skeleton, { className: "w-32" }), _jsx(Skeleton, { className: "w-40" })] })) : (_jsxs(_Fragment, { children: [installed.map(group), installed.length === 0 && _jsx("p", { className: "px-3 py-2 text-xs text-text-muted", children: t('list.none') }), missing.length > 0 && (_jsxs("div", { className: "mt-1.5 flex min-w-0 shrink-0 flex-col border-t border-border pt-2.5 pb-2", children: [_jsx(SectionLabel, { className: "px-3 pt-1 pb-1.5", children: t('list.notInstalled') }), missing.map((cli) => (_jsxs("div", { className: "flex h-10 min-w-0 items-center gap-3 px-3 text-sm text-text-muted", children: [_jsx(Icon, { icon: Terminal, size: 14, className: "shrink-0" }), _jsx("span", { className: "min-w-0 grow truncate", children: cli.name }), _jsx("span", { className: "shrink-0 text-xs text-text-faint", children: t('list.missing') })] }, cli.kind))), _jsx("p", { className: "mt-1 px-3 text-xs text-text-faint", children: t('list.notInstalledNote') })] }))] }));
+    const list = !loaded ? (_jsxs("div", { className: "flex flex-col gap-3 p-3", children: [_jsx(Skeleton, { className: "w-32" }), _jsx(Skeleton, { className: "w-40" })] })) : (_jsxs(_Fragment, { children: [installed.map(group), installed.length === 0 && _jsx("p", { className: "px-3 py-2 text-xs text-text-muted", children: t('list.none') }), missing.length > 0 && (_jsxs("div", { className: "mt-1.5 flex min-w-0 shrink-0 flex-col border-t border-border pt-2.5 pb-2", children: [_jsx(SectionLabel, { className: "px-3 pt-1 pb-1.5", children: t('list.notInstalled') }), missing.map((cli) => (_jsxs(ListRow, { selected: picksCli(cli.kind), onSelect: () => setPicked({ kind: 'install', cli: cli.kind }), children: [_jsx(CliMark, { kind: cli.kind, className: "opacity-60" }), _jsx("span", { className: "min-w-0 grow truncate text-xs font-medium text-text-muted", children: cli.name }), _jsx("span", { className: "shrink-0 text-xs text-text-faint", children: t('list.missing') })] }, cli.kind))), missing.every((cli) => cli.install === undefined) && _jsx("p", { className: "mt-1 px-3 text-xs text-text-faint", children: t('list.notInstalledNote') })] }))] }));
     const detail = () => {
         if (current === null || provider === null) {
             return null;
         }
-        const own = current.kind === 'cli' ? (detailOf?.(provider) ?? null) : null;
+        if (current.kind === 'install') {
+            const extra = installStepOf?.(provider) ?? null;
+            const statuses = entriesOf(provider.kind).map((entry) => entry.status?.state);
+            // Without accounts to read, nothing says the CLI is signed out, so being there is all it takes.
+            const signedIn = statuses.length === 0 || statuses.includes('ready');
+            if (!provider.installed || !signedIn || (extra !== null && !extra.done)) {
+                return _jsx(InstallPage, { provider: provider, signedIn: signedIn, extra: extra }, provider.kind);
+            }
+        }
+        const own = current.kind === 'cli' || current.kind === 'install' ? (detailOf?.(provider) ?? null) : null;
         if (own !== null) {
             return own;
         }

package/dist/providers/index.d.ts

@@ -7,4 +7,5 @@ export { modelName, useModelName, shortModelName } from '../agents/model-name.js
 export { carryOptions } from '../agents/model-options.js';
 export { type ModelRequirement } from '../agents/model-requirement.js';
 export { ProvidersPane } from './ProvidersPane.js';
+export type { ProviderInstallStep } from './install-steps.js';
 export { CliMark, CliTile } from './parts.js';

package/dist/providers/install-steps.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { ProviderInfo, ProviderPlatform } from '@adecore/agent-contracts';
+export interface ProviderInstallStep {
+    title: string;
+    done: boolean;
+    body: ReactNode;
+}
+export type InstallStepState = 'done' | 'current' | 'later';
+export declare function installStepStates(done: readonly boolean[]): InstallStepState[];
+export declare function pagePlatform(): ProviderPlatform;
+export declare function installPlatforms(provider: ProviderInfo, machine: ProviderPlatform): {
+    offered: ProviderPlatform[];
+    initial: ProviderPlatform | null;
+};

package/dist/providers/install-steps.js

@@ -0,0 +1,19 @@
+import { isApplePlatform } from '@adecore/ui';
+const PLATFORMS = ['darwin', 'linux', 'win32'];
+/* The first step not done is the current one. */
+export function installStepStates(done) {
+    const first = done.indexOf(false);
+    return done.map((value, index) => (value ? 'done' : index === first ? 'current' : 'later'));
+}
+/* The system of the page, for a host that does not say which system its machine runs. */
+export function pagePlatform() {
+    if (isApplePlatform()) {
+        return 'darwin';
+    }
+    return typeof navigator !== 'undefined' && /windows/i.test(navigator.userAgent) ? 'win32' : 'linux';
+}
+/* The systems a provider has a command for, and the one the page opens on: the machine's when it has one there. */
+export function installPlatforms(provider, machine) {
+    const offered = PLATFORMS.filter((platform) => Boolean(provider.install?.commands[platform]));
+    return { offered, initial: offered.includes(machine) ? machine : (offered[0] ?? null) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents-react",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "React agent chat threads, composers, approvals, provider accounts and usage views.",
   "type": "module",
   "exports": {
@@ -67,11 +67,11 @@
     "test:visuals": "bun --config=integration.bunfig.toml --conditions=source test ./src/chat/visual-viewport.integration.test.ts"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.31.0",
-    "@adecore/editor": "0.31.0",
-    "@adecore/editor-react": "0.31.0",
-    "@adecore/intelligent-ui": "0.31.0",
-    "@adecore/merge": "0.31.0",
+    "@adecore/agent-contracts": "0.31.1",
+    "@adecore/editor": "0.31.1",
+    "@adecore/editor-react": "0.31.1",
+    "@adecore/intelligent-ui": "0.31.1",
+    "@adecore/merge": "0.31.1",
     "@codemirror/commands": "^6.11.1",
     "@codemirror/language": "^6.12.4",
     "@codemirror/state": "^6.7.6",
@@ -94,14 +94,14 @@
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
-    "@adecore/ui": "^0.31.0",
+    "@adecore/ui": "^0.31.1",
     "i18next": "^26.4.2",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-i18next": "^17.0.15"
   },
   "devDependencies": {
-    "@adecore/ui": "0.31.0",
+    "@adecore/ui": "0.31.1",
     "@types/bun": "^1.4.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",

package/src/host.ts

@@ -14,7 +14,8 @@ import type {
     ChatUiQueryPayload,
     ChatUiQueryReading,
     ChatUiLinkPayload,
-    ChatUiLinkReading
+    ChatUiLinkReading,
+    ProviderPlatform
 } from '@adecore/agent-contracts';
 import { isApplePlatform } from '@adecore/ui';
 import type { TimelineRow } from './chat/logic/timeline';
@@ -384,6 +385,15 @@ export interface ChatHost {
     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;
+    /*
+     * Runs a command a provider's install page shows, its install or its sign-in, where a person sees it run,
+     * such as in a new terminal on the scope's machine; left out, the page offers to copy the command only.
+     */
+    runProviderCommand?(scopeId: string, kind: AgentKind, command: string): void;
+    /* The system of the machine the scope's chats run on, whose install command the page shows first; left out, or null, the system of this page. */
+    useMachinePlatform?(scopeId: string): ProviderPlatform | null;
+    /* A sentence under a key the install page asks for in the environment, such as what the app does with it; left out, or null, none. */
+    providerKeyNote?(variable: 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;
     /* What a person calls the machine the scope's chats run on, or null when it has no name worth saying. */

package/src/locales/en/agent-providers.ts

@@ -18,10 +18,47 @@ export default {
         addAccount: 'Add a {{provider}} account',
         notInstalled: 'Not installed',
         missing: 'Missing',
-        notInstalledNote: 'To add one, install it and restart Ruimte on that machine.',
+        notInstalledNote: 'Install one on this machine to use it here.',
         none: 'No agent CLIs found on this machine.',
         noAccounts: 'This machine keeps no accounts yet. Update Ruimte there to add one.'
     },
+    install: {
+        notInstalled: 'Not installed',
+        steps: 'Steps to set up {{provider}}',
+        platform: 'System',
+        platforms: {
+            darwin: 'macOS',
+            linux: 'Linux',
+            win32: 'Windows'
+        },
+        copy: 'Copy',
+        copied: 'Copied',
+        run: 'Run in a terminal',
+        guide: 'Install guide',
+        install: {
+            title: 'Install the CLI',
+            none: 'There is no install command for this system.',
+            done: 'Installed, version {{version}}.',
+            doneNoVersion: 'Installed.'
+        },
+        signIn: {
+            title: 'Sign in',
+            command: 'Run this in a terminal and follow its steps:',
+            env: 'Set <code>{{variable}}</code> in the environment the CLI starts in.',
+            chat: 'The first chat asks you to sign in.',
+            or: 'Or',
+            unknown: 'The CLI asks you to sign in the first time it runs.'
+        },
+        start: {
+            title: 'Start working',
+            description: 'Pick {{provider}} for your next chat or terminal.'
+        },
+        footer: {
+            missing: 'Not found on this machine yet. It is checked again when you come back to this window.',
+            found: 'Found on this machine.'
+        },
+        fallback: 'Install {{provider}} on this machine to use it here.'
+    },
     abilities: {
         version: 'Version {{version}}.',
         chatAndTerminal: 'Chat and terminal.',

package/src/locales/nl/agent-providers.ts

@@ -18,10 +18,47 @@ export default {
         addAccount: 'Een {{provider}}-account toevoegen',
         notInstalled: 'Niet geïnstalleerd',
         missing: 'Ontbreekt',
-        notInstalledNote: 'Installeer er een en start Ruimte op die machine opnieuw om hem toe te voegen.',
+        notInstalledNote: 'Installeer er een op deze machine om hem hier te gebruiken.',
         none: "Geen agent-CLI's gevonden op deze machine.",
         noAccounts: 'Deze machine houdt nog geen accounts bij. Werk Ruimte daar bij om er een toe te voegen.'
     },
+    install: {
+        notInstalled: 'Niet geïnstalleerd',
+        steps: '{{provider}} instellen in stappen',
+        platform: 'Systeem',
+        platforms: {
+            darwin: 'macOS',
+            linux: 'Linux',
+            win32: 'Windows'
+        },
+        copy: 'Kopiëren',
+        copied: 'Gekopieerd',
+        run: 'In een terminal uitvoeren',
+        guide: 'Installatiegids',
+        install: {
+            title: 'Installeer de CLI',
+            none: 'Er is geen installatiecommando voor dit systeem.',
+            done: 'Geïnstalleerd, versie {{version}}.',
+            doneNoVersion: 'Geïnstalleerd.'
+        },
+        signIn: {
+            title: 'Log in',
+            command: 'Voer dit uit in een terminal en volg de stappen:',
+            env: 'Zet <code>{{variable}}</code> in de omgeving waarin de CLI start.',
+            chat: 'De eerste chat vraagt je om in te loggen.',
+            or: 'Of',
+            unknown: 'De CLI vraagt je om in te loggen als hij voor het eerst draait.'
+        },
+        start: {
+            title: 'Aan de slag',
+            description: 'Kies {{provider}} voor je volgende chat of terminal.'
+        },
+        footer: {
+            missing: 'Nog niet gevonden op deze machine. Er wordt opnieuw gekeken als je terugkomt in dit venster.',
+            found: 'Gevonden op deze machine.'
+        },
+        fallback: 'Installeer {{provider}} op deze machine om hem hier te gebruiken.'
+    },
     abilities: {
         version: 'Versie {{version}}.',
         chatAndTerminal: 'Chat en terminal.',

package/src/providers/InstallPage.tsx

@@ -0,0 +1,221 @@
+import { useState, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Trans, useTranslation } from 'react-i18next';
+import { Check, Copy, ExternalLink, SquareTerminal } from 'lucide-react';
+import type { ProviderInfo, ProviderPlatform, ProviderSignIn } from '@adecore/agent-contracts';
+import { Button, copyText, Icon, Pill, Segmented } from '@adecore/ui';
+import { useChatHost } from '../host';
+import { useChatScope } from '../scope';
+import { installPlatforms, installStepStates, pagePlatform, type InstallStepState, type ProviderInstallStep } from './install-steps';
+import { CliMark } from './parts';
+
+const noPlatform = (): ProviderPlatform | null => null;
+
+function CommandBlock({ command }: { command: string }) {
+    const { t } = useTranslation('agent-providers');
+    const [copied, setCopied] = useState<string | null>(null);
+    return (
+        <div className="flex min-w-0 items-center gap-2 rounded-lg border border-border bg-surface-sunken py-1 pr-1 pl-3">
+            <code className="min-w-0 grow font-mono text-code break-all text-text select-text">{command}</code>
+            <Button
+                size="xs"
+                onClick={() => {
+                    copyText(command);
+                    setCopied(command);
+                }}
+            >
+                <Icon icon={copied === command ? Check : Copy} size={12} />
+                {copied === command ? t('install.copied') : t('install.copy')}
+            </Button>
+        </div>
+    );
+}
+
+function Step({ index, state, title, children }: { index: number; state: InstallStepState; title: string; children?: ReactNode }) {
+    return (
+        <li
+            aria-current={state === 'current' ? 'step' : undefined}
+            data-state={state}
+            className={clsx('flex min-w-0 gap-3 rounded-xl border p-4', state === 'current' ? 'border-accent' : 'border-border')}
+        >
+            <span
+                className={clsx(
+                    'grid size-6 shrink-0 place-items-center rounded-full text-xs font-medium',
+                    state === 'done' && 'bg-positive text-positive-text',
+                    state === 'current' && 'border border-accent text-accent',
+                    state === 'later' && 'bg-text/7 text-text-faint'
+                )}
+            >
+                {state === 'done' ? <Icon icon={Check} size={14} /> : index + 1}
+            </span>
+            <div className="flex min-w-0 grow flex-col gap-3">
+                <h4 className={clsx('text-sm leading-6 font-medium', state === 'later' ? 'text-text-muted' : 'text-text')}>{title}</h4>
+                {children}
+            </div>
+        </li>
+    );
+}
+
+function SignInWay({ way, canRun, onRun }: { way: ProviderSignIn; canRun: boolean; onRun(command: string): void }) {
+    const { t } = useTranslation('agent-providers');
+    const { providerKeyNote } = useChatHost();
+    switch (way.kind) {
+        case 'command':
+            return (
+                <div className="flex min-w-0 flex-col gap-2">
+                    <p className="text-xs text-text-muted">{t('install.signIn.command')}</p>
+                    <CommandBlock command={way.command} />
+                    {canRun && (
+                        <Button variant="secondary" size="sm" className="self-start" onClick={() => onRun(way.command)}>
+                            <Icon icon={SquareTerminal} size={14} />
+                            {t('install.run')}
+                        </Button>
+                    )}
+                </div>
+            );
+        case 'env': {
+            const note = providerKeyNote?.(way.variable) ?? null;
+            return (
+                <p className="text-xs text-text-muted">
+                    <Trans
+                        t={t}
+                        i18nKey="install.signIn.env"
+                        values={{ variable: way.variable }}
+                        components={{ code: <code className="font-mono text-code text-text" /> }}
+                    />
+                    {note !== null && ` ${note}`}
+                </p>
+            );
+        }
+        case 'chat':
+            return <p className="text-xs text-text-muted">{t('install.signIn.chat')}</p>;
+    }
+}
+
+interface InstallPageProps {
+    provider: ProviderInfo;
+    signedIn: boolean;
+    /* The host's own step, after the install of the CLI. */
+    extra: ProviderInstallStep | null;
+}
+
+/* How to get a CLI that is not on the machine yet, step by step, until it is there and signed in. */
+export function InstallPage({ provider, signedIn, extra }: InstallPageProps) {
+    const { t } = useTranslation('agent-providers');
+    const { id: scopeId } = useChatScope();
+    const host = useChatHost();
+    const useMachinePlatform = host.useMachinePlatform ?? noPlatform;
+    const machine = useMachinePlatform(scopeId) ?? pagePlatform();
+    const { offered, initial } = installPlatforms(provider, machine);
+    // Only a person's pick is kept, so a machine whose system arrives late still opens on its own.
+    const [chosen, setPlatform] = useState<ProviderPlatform | null>(null);
+    const platform = chosen ?? initial;
+    const install = provider.install;
+    const run = host.runProviderCommand;
+    const onRun = (command: string): void => run?.(scopeId, provider.kind, command);
+    const command = platform === null ? undefined : install?.commands[platform];
+
+    const steps: { title: string; done: boolean; body: ReactNode }[] = [];
+    steps.push({
+        title: t('install.install.title'),
+        done: provider.installed,
+        body: provider.installed ? (
+            <p className="text-xs text-text-muted">
+                {provider.version ? t('install.install.done', { version: provider.version }) : t('install.install.doneNoVersion')}
+            </p>
+        ) : (
+            <>
+                {offered.length > 1 && platform !== null && (
+                    <Segmented<ProviderPlatform>
+                        value={platform}
+                        label={t('install.platform')}
+                        options={offered.map((id) => ({ id, label: t(`install.platforms.${id}`) }))}
+                        onValueChange={setPlatform}
+                    />
+                )}
+                {command ? <CommandBlock command={command} /> : <p className="text-xs text-text-muted">{t('install.install.none')}</p>}
+                {((command && run) || install?.guideUrl) && (
+                    <div className="flex flex-wrap items-center gap-2">
+                        {command && run && (
+                            <Button variant="primary" onClick={() => onRun(command)}>
+                                <Icon icon={SquareTerminal} size={14} />
+                                {t('install.run')}
+                            </Button>
+                        )}
+                        {install?.guideUrl && (
+                            <Button href={install.guideUrl}>
+                                {t('install.guide')}
+                                <Icon icon={ExternalLink} size={14} />
+                            </Button>
+                        )}
+                    </div>
+                )}
+            </>
+        )
+    });
+    if (extra !== null) {
+        steps.push(extra);
+    }
+    const ways = install?.signIn ?? [];
+    steps.push({
+        title: t('install.signIn.title'),
+        done: provider.installed && signedIn,
+        body:
+            ways.length === 0 ? (
+                <p className="text-xs text-text-muted">{t('install.signIn.unknown')}</p>
+            ) : (
+                ways.map((way, index) => (
+                    <div key={`${way.kind}-${index}`} className="flex min-w-0 flex-col gap-2">
+                        {index > 0 && <span className="text-xs font-medium text-text-faint">{t('install.signIn.or')}</span>}
+                        <SignInWay way={way} canRun={run !== undefined && provider.installed} onRun={onRun} />
+                    </div>
+                ))
+            )
+    });
+    steps.push({
+        title: t('install.start.title'),
+        done: false,
+        body: <p className="text-xs text-text-muted">{t('install.start.description', { provider: provider.name })}</p>
+    });
+    const states = installStepStates(steps.map((step) => step.done));
+
+    return (
+        <>
+            <header className="flex min-w-0 items-start gap-3">
+                <span className="grid size-10 shrink-0 place-items-center rounded-xl bg-surface-sunken">
+                    <CliMark kind={provider.kind} size={20} />
+                </span>
+                <div className="flex min-w-0 grow flex-col">
+                    <div className="flex min-w-0 items-center gap-2">
+                        <h3 className="truncate text-lg font-semibold text-text">{provider.name}</h3>
+                        {provider.installed ? (
+                            provider.version && (
+                                <Pill tone="idle" mono>
+                                    {provider.version}
+                                </Pill>
+                            )
+                        ) : (
+                            <Pill>{t('install.notInstalled')}</Pill>
+                        )}
+                    </div>
+                    {install && <p className="text-xs text-text-muted">{install.description}</p>}
+                </div>
+            </header>
+            {install ? (
+                <ol aria-label={t('install.steps', { provider: provider.name })} className="flex min-w-0 flex-col gap-3">
+                    {steps.map((step, index) => (
+                        <Step key={index} index={index} state={states[index]!} title={step.title}>
+                            {step.body}
+                        </Step>
+                    ))}
+                </ol>
+            ) : (
+                <p className="text-xs text-text-muted">{t('install.fallback', { provider: provider.name })}</p>
+            )}
+            <p className="flex min-w-0 items-center gap-2 text-xs text-text-muted">
+                <span aria-hidden className={clsx('size-2 shrink-0 rounded-full', provider.installed ? 'bg-status-idle' : 'bg-text-faint')} />
+                {provider.installed ? t('install.footer.found') : t('install.footer.missing')}
+            </p>
+        </>
+    );
+}

package/src/providers/ProvidersPane.tsx

@@ -1,22 +1,25 @@
 import { useMemo, useState, type ReactNode } from 'react';
 import clsx from 'clsx';
 import { useTranslation } from 'react-i18next';
-import { Plus, Terminal } from 'lucide-react';
+import { Plus } from 'lucide-react';
 import type { AgentKind, ProviderInfo } from '@adecore/agent-contracts';
 import { AccountDot } from '../agents/AccountDot';
 import { ACCOUNT_TONE_CLASSES, accountLoginOf, accountName, accountsOfKind, accountStatusLine, type AccountEntry } from '../agents/accounts';
-import { ErrorBoundary, Icon, IconButton, SectionLabel, Skeleton } from '@adecore/ui';
+import { ErrorBoundary, IconButton, SectionLabel, Skeleton } from '@adecore/ui';
 import { MasterDetail } from '@adecore/ui/settings';
 import { useChatHost } from '../host';
 import { useChatScope } from '../scope';
 import { AccountDetail } from './AccountDetail';
 import { AddAccountForm } from './AddAccountForm';
 import { CliDetail } from './CliDetail';
+import { InstallPage } from './InstallPage';
+import type { ProviderInstallStep } from './install-steps';
 import { CliMark } from './parts';
 import { useProviderAccounts } from '../state/provider-accounts';
 import { useProviders } from '../state/providers';
 
-type Picked = { kind: 'cli'; cli: AgentKind } | { kind: 'account'; id: string } | { kind: 'add'; cli: AgentKind };
+// `install` is a CLI picked while it was missing: its install page stays until it is installed and signed in.
+type Picked = { kind: 'cli'; cli: AgentKind } | { kind: 'install'; cli: AgentKind } | { kind: 'account'; id: string } | { kind: 'add'; cli: AgentKind };
 
 /* A row of the list with a control of its own beside the part that picks it, so the two never nest. */
 function ListRow({
@@ -54,10 +57,12 @@ interface ProvidersPaneProps {
     detailOf?(provider: ProviderInfo): ReactNode | null;
     /* False leaves "Defaults for new chats" out of a CLI's detail, for an app that decides those elsewhere. */
     defaults?: boolean;
+    /* A step of the app's own on the install page of a CLI, after its install, such as a server its chat needs; null adds none. */
+    installStepOf?(provider: ProviderInfo): ProviderInstallStep | null;
 }
 
 /* The agent CLIs of the host in scope, each with its accounts, beside the detail of what is picked. */
-export function ProvidersPane({ target = null, detailOf, defaults = true }: ProvidersPaneProps) {
+export function ProvidersPane({ target = null, detailOf, defaults = true, installStepOf }: ProvidersPaneProps) {
     const { t } = useTranslation('agent-providers');
     const { id: scopeId } = useChatScope();
     const providers = useProviders((s) => s.providers);
@@ -80,7 +85,8 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }: Prov
         picked !== null && (picked.kind !== 'account' || pickedEntry !== null) ? picked : installed[0] ? { kind: 'cli', cli: installed[0].kind } : null;
     const currentAccount = current?.kind === 'account' ? accounts?.accounts[current.id] : undefined;
     const currentCli = current === null ? null : current.kind === 'account' ? (currentAccount?.kind as AgentKind | undefined) : current.cli;
-    const provider = installed.find((entry) => entry.kind === currentCli) ?? null;
+    const provider = (current?.kind === 'install' ? providers : installed).find((entry) => entry.kind === currentCli) ?? null;
+    const picksCli = (kind: AgentKind): boolean => (current?.kind === 'cli' || current?.kind === 'install') && current.cli === kind;
 
     // A search result lands on a row of a CLI's detail, so a picked account makes way for its CLI.
     const [seenTarget, setSeenTarget] = useState(target);
@@ -105,7 +111,7 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }: Prov
         return (
             <div key={cli.kind} className="flex min-w-0 shrink-0 flex-col gap-0.5 pt-1">
                 <ListRow
-                    selected={current?.kind === 'cli' && current.cli === cli.kind}
+                    selected={picksCli(cli.kind)}
                     onSelect={() => setPicked({ kind: 'cli', cli: cli.kind })}
                     className="pr-1"
                     trailing={
@@ -164,13 +170,13 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }: Prov
                 <div className="mt-1.5 flex min-w-0 shrink-0 flex-col border-t border-border pt-2.5 pb-2">
                     <SectionLabel className="px-3 pt-1 pb-1.5">{t('list.notInstalled')}</SectionLabel>
                     {missing.map((cli) => (
-                        <div key={cli.kind} className="flex h-10 min-w-0 items-center gap-3 px-3 text-sm text-text-muted">
-                            <Icon icon={Terminal} size={14} className="shrink-0" />
-                            <span className="min-w-0 grow truncate">{cli.name}</span>
+                        <ListRow key={cli.kind} selected={picksCli(cli.kind)} onSelect={() => setPicked({ kind: 'install', cli: cli.kind })}>
+                            <CliMark kind={cli.kind} className="opacity-60" />
+                            <span className="min-w-0 grow truncate text-xs font-medium text-text-muted">{cli.name}</span>
                             <span className="shrink-0 text-xs text-text-faint">{t('list.missing')}</span>
-                        </div>
+                        </ListRow>
                     ))}
-                    <p className="mt-1 px-3 text-xs text-text-faint">{t('list.notInstalledNote')}</p>
+                    {missing.every((cli) => cli.install === undefined) && <p className="mt-1 px-3 text-xs text-text-faint">{t('list.notInstalledNote')}</p>}
                 </div>
             )}
         </>
@@ -180,7 +186,16 @@ export function ProvidersPane({ target = null, detailOf, defaults = true }: Prov
         if (current === null || provider === null) {
             return null;
         }
-        const own = current.kind === 'cli' ? (detailOf?.(provider) ?? null) : null;
+        if (current.kind === 'install') {
+            const extra = installStepOf?.(provider) ?? null;
+            const statuses = entriesOf(provider.kind).map((entry) => entry.status?.state);
+            // Without accounts to read, nothing says the CLI is signed out, so being there is all it takes.
+            const signedIn = statuses.length === 0 || statuses.includes('ready');
+            if (!provider.installed || !signedIn || (extra !== null && !extra.done)) {
+                return <InstallPage key={provider.kind} provider={provider} signedIn={signedIn} extra={extra} />;
+            }
+        }
+        const own = current.kind === 'cli' || current.kind === 'install' ? (detailOf?.(provider) ?? null) : null;
         if (own !== null) {
             return own;
         }

package/src/providers/index.ts

@@ -8,4 +8,5 @@ export { modelName, useModelName, shortModelName } from '../agents/model-name';
 export { carryOptions } from '../agents/model-options';
 export { type ModelRequirement } from '../agents/model-requirement';
 export { ProvidersPane } from './ProvidersPane';
+export type { ProviderInstallStep } from './install-steps';
 export { CliMark, CliTile } from './parts';

package/src/providers/install-steps.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import type { ProviderInfo, ProviderPlatform } from '@adecore/agent-contracts';
+import { isApplePlatform } from '@adecore/ui';
+
+/* A step of the host's own on a provider's install page, such as a server its chat needs beside the CLI. */
+export interface ProviderInstallStep {
+    title: string;
+    done: boolean;
+    /* Drawn under the title; the page numbers the step and outlines it while it is the current one. */
+    body: ReactNode;
+}
+
+export type InstallStepState = 'done' | 'current' | 'later';
+
+const PLATFORMS: readonly ProviderPlatform[] = ['darwin', 'linux', 'win32'];
+
+/* The first step not done is the current one. */
+export function installStepStates(done: readonly boolean[]): InstallStepState[] {
+    const first = done.indexOf(false);
+    return done.map((value, index) => (value ? 'done' : index === first ? 'current' : 'later'));
+}
+
+/* The system of the page, for a host that does not say which system its machine runs. */
+export function pagePlatform(): ProviderPlatform {
+    if (isApplePlatform()) {
+        return 'darwin';
+    }
+    return typeof navigator !== 'undefined' && /windows/i.test(navigator.userAgent) ? 'win32' : 'linux';
+}
+
+/* The systems a provider has a command for, and the one the page opens on: the machine's when it has one there. */
+export function installPlatforms(provider: ProviderInfo, machine: ProviderPlatform): { offered: ProviderPlatform[]; initial: ProviderPlatform | null } {
+    const offered = PLATFORMS.filter((platform) => Boolean(provider.install?.commands[platform]));
+    return { offered, initial: offered.includes(machine) ? machine : (offered[0] ?? null) };
+}