@adecore/agents 0.29.2 → 0.30.0

package/src/chat/json-rpc-transport.ts

@@ -0,0 +1,253 @@
+import { errorText } from '../error-text.ts';
+import { ChatChild, MAX_LINE_LENGTH, readStreamLines, type SpawnChatProcess } from './chat-process.ts';
+
+export type JsonRpcFrame = Record<string, unknown>;
+
+export interface JsonRpcTransportOptions {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    // How the agent is named in the errors this transport raises.
+    label: string;
+    // The `name` of an error the agent answered with, which callers tell apart from a silence or an exit.
+    errorName?: string;
+    // How long a request may go unanswered; null waits for as long as the process runs.
+    requestTimeoutMs: number | null;
+    // Whether every frame carries `"jsonrpc": "2.0"`; a protocol that leaves it out reads it as noise.
+    versionField?: boolean;
+    // Notifications and server requests; responses to our own requests settle their promise instead.
+    onFrame(frame: JsonRpcFrame): void;
+    onError?(error: Error): void;
+    // `stderr` is the tail of what the process wrote there, for an exit with an error code only.
+    onExit(exitCode: number | null, stderr: string | null): void;
+}
+
+export interface JsonRpcRequestOptions {
+    // Overrides the transport's timeout for this request; null waits for as long as the process runs.
+    timeoutMs?: number | null;
+}
+
+/* An error the other side answered a request with. */
+export class JsonRpcError extends Error {
+    readonly code: number | null;
+    readonly data: unknown;
+
+    constructor(name: string, method: string, error: unknown) {
+        const detail = typeof error === 'object' && error !== null ? (error as { message?: unknown; code?: unknown; data?: unknown }) : {};
+        super(`${method} failed: ${typeof detail.message === 'string' ? detail.message : JSON.stringify(error)}`);
+        this.name = name;
+        this.code = typeof detail.code === 'number' ? detail.code : null;
+        this.data = detail.data;
+    }
+}
+
+type Settle = { resolve(value: unknown): void; reject(reason: Error): void; method: string; timer: ReturnType<typeof setTimeout> | null };
+
+/*
+ * One child process and JSON-RPC on its stdio: newline-delimited JSON, a request carries an id and
+ * gets a result or an error back under the same id, a notification has no id. The child also sends
+ * requests of its own, answered with `respond` or `respondError`.
+ */
+export class JsonRpcTransport {
+    private readonly child: ChatChild;
+    private readonly options: JsonRpcTransportOptions;
+    private readonly pending = new Map<number, Settle>();
+    private nextId = 1;
+    private closed = false;
+    // Set once stdin ended or broke; a write after an EPIPE only raises the next one.
+    private inputClosed = false;
+
+    constructor(options: JsonRpcTransportOptions) {
+        this.options = options;
+        this.child = new ChatChild({
+            command: options.command,
+            cwd: options.cwd,
+            env: options.env,
+            ...(options.spawn ? { spawn: options.spawn } : {}),
+            onError: (error) => this.broken(error),
+            onExit: (exitCode, stderr) => this.handleExit(exitCode, stderr)
+        });
+        void this.readLines();
+    }
+
+    get pid(): number {
+        return this.child.pid;
+    }
+
+    get alive(): boolean {
+        return !this.closed;
+    }
+
+    request(method: string, params: unknown, options: JsonRpcRequestOptions = {}): Promise<unknown> {
+        const label = this.options.label;
+        const timeoutMs = options.timeoutMs === undefined ? this.options.requestTimeoutMs : options.timeoutMs;
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error(`${method} failed: ${label} is not running`));
+                return;
+            }
+            const id = this.nextId++;
+            let timer: ReturnType<typeof setTimeout> | null = null;
+            if (timeoutMs !== null) {
+                timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`${method} failed: ${label} did not answer in ${timeoutMs / 1000} seconds`));
+                }, timeoutMs);
+                timer.unref?.();
+            }
+            this.pending.set(id, { resolve, reject, method, timer });
+            try {
+                this.write({ id, method, params });
+            } catch (error) {
+                if (timer !== null) {
+                    clearTimeout(timer);
+                }
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+
+    notify(method: string, params: unknown): void {
+        this.write({ method, params });
+    }
+
+    respond(id: number | string, result: unknown): void {
+        this.write({ id, result });
+    }
+
+    respondError(id: number | string, code: number, message: string): void {
+        this.write({ id, error: { code, message } });
+    }
+
+    /* Closes stdin; the child ends on its own once it has nothing more to say. */
+    end(): void {
+        this.inputClosed = true;
+        try {
+            this.child.process.stdin.end();
+        } catch {
+            // Already closed by the other side.
+        }
+    }
+
+    kill(signal: 'SIGTERM' | 'SIGKILL' = 'SIGTERM'): void {
+        this.child.process.kill(signal);
+    }
+
+    stop(): void {
+        this.end();
+        this.child.endAfterGrace();
+    }
+
+    dispose(): Promise<void> {
+        return this.child.end();
+    }
+
+    private write(frame: JsonRpcFrame): void {
+        if (this.closed || this.inputClosed) {
+            throw new Error(`${this.options.label} stdin is closed`);
+        }
+        try {
+            const framed = this.options.versionField ? { jsonrpc: '2.0', ...frame } : frame;
+            this.child.process.stdin.write(`${JSON.stringify(framed)}\n`);
+            this.child.process.stdin.flush();
+        } catch (error) {
+            this.inputClosed = true;
+            throw error;
+        }
+    }
+
+    /* A pipe that failed takes no more writes; a frame a consumer choked on leaves it as it was. */
+    private broken(error: unknown): void {
+        this.inputClosed = true;
+        this.failed(error);
+    }
+
+    private failed(error: unknown): void {
+        const failure = new Error(`${this.options.label} transport failed: ${errorText(error)}`);
+        this.rejectPending(() => failure);
+        try {
+            this.options.onError?.(failure);
+        } catch (reportError) {
+            console.error(`Reporting a ${this.options.label} transport failure failed:`, errorText(reportError));
+        }
+    }
+
+    private readLine(line: string): void {
+        try {
+            this.handleLine(line);
+        } catch (error) {
+            this.failed(error);
+        }
+    }
+
+    private async readLines(): Promise<void> {
+        try {
+            await readStreamLines(
+                this.child.process.stdout,
+                (line) => this.readLine(line),
+                () =>
+                    this.failed(
+                        new Error(`${this.options.label} wrote a frame of more than ${MAX_LINE_LENGTH / 1_000_000} million characters, which was dropped`)
+                    )
+            );
+        } catch (error) {
+            if (!this.closed) {
+                this.broken(error);
+            }
+        }
+    }
+
+    private handleLine(line: string): void {
+        if (this.closed || line.trim() === '') {
+            return;
+        }
+        let frame: unknown;
+        try {
+            frame = JSON.parse(line);
+        } catch {
+            return;
+        }
+        if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) {
+            return;
+        }
+        const message = frame as JsonRpcFrame;
+        if (typeof message.method === 'string') {
+            this.options.onFrame(message);
+            return;
+        }
+        const settle = typeof message.id === 'number' ? this.pending.get(message.id) : undefined;
+        if (!settle) {
+            return;
+        }
+        this.pending.delete(message.id as number);
+        if (settle.timer !== null) {
+            clearTimeout(settle.timer);
+        }
+        if (message.error !== undefined) {
+            settle.reject(new JsonRpcError(this.options.errorName ?? 'JsonRpcError', settle.method, message.error));
+        } else {
+            settle.resolve(message.result);
+        }
+    }
+
+    private handleExit(exitCode: number | null, stderr: string | null): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.rejectPending((method) => new Error(`${method} failed: ${this.options.label} exited`));
+        this.options.onExit(exitCode, stderr);
+    }
+
+    private rejectPending(reason: (method: string) => Error): void {
+        for (const settle of this.pending.values()) {
+            if (settle.timer !== null) {
+                clearTimeout(settle.timer);
+            }
+            settle.reject(reason(settle.method));
+        }
+        this.pending.clear();
+    }
+}

package/src/providers/accounts/accounts.ts

@@ -1,15 +1,22 @@
 import { isAbsolute, join, resolve } from 'node:path';
-import { AgentKindSchema, ProviderAccountSchema, type AgentKind, type ProviderAccount, type ProviderAccountMap } from '@adecore/agent-contracts';
+import { KNOWN_AGENT_KINDS, ProviderAccountSchema, type AgentKind, type ProviderAccount, type ProviderAccountMap } from '@adecore/agent-contracts';
 import type { ChatProvider } from '../provider.ts';
 import { DEFAULT_ACCOUNTS_HOST, variablesProblem, type AccountsHost, type ReservedVariables } from './variables.ts';
 import { homeFolder } from '../../home-folder.ts';
 
 export type Env = Record<string, string | undefined>;
 
-const KNOWN_KINDS: readonly string[] = AgentKindSchema.options;
+/*
+ * The CLIs a host keeps accounts for, in catalog order, and the provider of any kind. An account of
+ * a kind outside `kinds` is kept as it was written and never judged, for a host that offers it.
+ */
+export interface AccountProviders {
+    kinds: readonly AgentKind[];
+    get(kind: AgentKind): ChatProvider;
+}
 
-export function isKnownKind(kind: string): kind is AgentKind {
-    return KNOWN_KINDS.includes(kind);
+export function isOfferedKind(kind: string, kinds: readonly AgentKind[]): boolean {
+    return kinds.includes(kind);
 }
 
 /* The default account of a CLI is the folder the CLI uses without being told, and its id is the CLI's kind. */
@@ -42,9 +49,10 @@ export function accountProblem(
     account: ProviderAccount,
     provider: ChatProvider,
     env: Env,
-    reserved: ReservedVariables = { host: DEFAULT_ACCOUNTS_HOST, folderVariables: [] }
+    reserved: ReservedVariables = { host: DEFAULT_ACCOUNTS_HOST, folderVariables: [] },
+    kinds: readonly AgentKind[] = KNOWN_AGENT_KINDS
 ): string | null {
-    if (isKnownKind(id) && id !== account.kind) {
+    if (isOfferedKind(id, kinds) && id !== account.kind) {
         return `"${id}" is the id of the default ${id} account`;
     }
     const variables = variablesProblem(account.env ?? [], reserved);
@@ -79,17 +87,17 @@ export function accountProblem(
 }
 
 /* The variables that point a CLI at its folder, which no account may set by hand. */
-export function folderVariablesOf(providerOf: (kind: AgentKind) => ChatProvider): string[] {
-    return AgentKindSchema.options.flatMap((kind) => {
-        const home = providerOf(kind).home;
+export function folderVariablesOf(providers: AccountProviders): string[] {
+    return providers.kinds.flatMap((kind) => {
+        const home = providers.get(kind).home;
         return home === undefined ? [] : [home.env];
     });
 }
 
-/* The map with a default account for every CLI this version knows, those first and in catalog order. */
-export function withDefaults(accounts: ProviderAccountMap): ProviderAccountMap {
+/* The map with a default account for every CLI the host offers, those first and in catalog order. */
+export function withDefaults(accounts: ProviderAccountMap, kinds: readonly AgentKind[]): ProviderAccountMap {
     const complete: ProviderAccountMap = {};
-    for (const kind of KNOWN_KINDS) {
+    for (const kind of kinds) {
         complete[kind] = accounts[kind] ?? { kind };
     }
     for (const [id, account] of Object.entries(accounts)) {
@@ -151,15 +159,15 @@ export interface NamedAccount {
  * Whether a conversation of one account can go on under the other: the same CLI, reading the same
  * transcripts. Two Codex accounts over one `home` can, shadow home or not; two Claude folders never.
  */
-export function canContinue(from: NamedAccount, to: NamedAccount, providerOf: (kind: AgentKind) => ChatProvider, env: Env): boolean {
+export function canContinue(from: NamedAccount, to: NamedAccount, providers: AccountProviders, env: Env): boolean {
     if (from.id === to.id) {
         return true;
     }
     const kind = from.account.kind;
-    if (kind !== to.account.kind || !isKnownKind(kind)) {
+    if (kind !== to.account.kind || !isOfferedKind(kind, providers.kinds)) {
         return false;
     }
-    const provider = providerOf(kind);
+    const provider = providers.get(kind);
     return transcriptFolder(from.id, from.account, provider, env) === transcriptFolder(to.id, to.account, provider, env);
 }
 
@@ -167,13 +175,7 @@ export function canContinue(from: NamedAccount, to: NamedAccount, providerOf: (k
  * An account as the file holds it, or null for one to drop. An unknown kind comes back as it was
  * read, extra fields included; a known kind has to parse and make sense.
  */
-export function readAccount(
-    id: string,
-    raw: unknown,
-    providerOf: (kind: AgentKind) => ChatProvider,
-    env: Env,
-    host: AccountsHost = DEFAULT_ACCOUNTS_HOST
-): unknown {
+export function readAccount(id: string, raw: unknown, providers: AccountProviders, env: Env, host: AccountsHost = DEFAULT_ACCOUNTS_HOST): unknown {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         return null;
     }
@@ -181,11 +183,12 @@ export function readAccount(
     if (typeof kind !== 'string' || kind === '') {
         return null;
     }
-    if (!isKnownKind(kind)) {
-        return isKnownKind(id) ? null : raw;
+    if (!isOfferedKind(kind, providers.kinds)) {
+        return isOfferedKind(id, providers.kinds) ? null : raw;
     }
     const parsed = ProviderAccountSchema.safeParse(raw);
-    if (!parsed.success || accountProblem(id, parsed.data, providerOf(kind), env, { host, folderVariables: folderVariablesOf(providerOf) }) !== null) {
+    const reserved = { host, folderVariables: folderVariablesOf(providers) };
+    if (!parsed.success || accountProblem(id, parsed.data, providers.get(kind), env, reserved, providers.kinds) !== null) {
         return null;
     }
     return parsed.data;

package/src/providers/accounts/service.ts

@@ -2,7 +2,7 @@ import { existsSync, statSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import {
-    AgentKindSchema,
+    KNOWN_AGENT_KINDS,
     type AgentKind,
     type ProviderAccount,
     type ProviderAccountCreatePayload,
@@ -18,7 +18,18 @@ import { ClientSinks } from '../../client-sinks.ts';
 import { errorText } from '../../error-text.ts';
 import type { AgentEvent, AgentSink } from '../../events.ts';
 import type { ChatProvider } from '../provider.ts';
-import { accountEnv, accountFolder, canContinue, defaultFolder, expandHome, isDefaultAccount, isKnownKind, transcriptFolder, type Env } from './accounts.ts';
+import {
+    accountEnv,
+    accountFolder,
+    canContinue,
+    defaultFolder,
+    expandHome,
+    isDefaultAccount,
+    isOfferedKind,
+    transcriptFolder,
+    type AccountProviders,
+    type Env
+} from './accounts.ts';
 import { AccountError, isDefaultAccountOf, type AccountLaunches } from './launch.ts';
 import { prepareShadowHome, type ShadowHomeReport } from './shadow-home.ts';
 import { askAccountAs, type AskAccount } from './status.ts';
@@ -38,7 +49,8 @@ export interface ProviderAccountsOptions {
     host?: AccountsHost;
     // How the host names itself to an app-server it asks who is signed in.
     client?: CodexClientInfo;
-    providers: { list(): Promise<ProviderInfo[]>; get(kind: AgentKind): ChatProvider; enabled?(kind: AgentKind): boolean };
+    // `kinds` are the CLIs that get a default account; absent, every kind this version knows.
+    providers: { list(): Promise<ProviderInfo[]>; get(kind: AgentKind): ChatProvider; enabled?(kind: AgentKind): boolean; kinds?(): readonly AgentKind[] };
     env?: Env;
     // How to ask a CLI who is signed in; a test answers without starting one.
     ask?: AskAccount;
@@ -131,7 +143,7 @@ export class ProviderAccountsService implements AccountLaunches {
     private readonly launches = new Map<string, number>();
     private readonly states = new Map<string, AccountState>();
     private stored: StoredAccounts = {};
-    private accounts: ProviderAccountMap = wireAccounts({});
+    private accounts: ProviderAccountMap;
     private passes: Promise<void> = Promise.resolve();
     private timer: ReturnType<typeof setInterval> | null = null;
 
@@ -148,11 +160,12 @@ export class ProviderAccountsService implements AccountLaunches {
         this.secrets = options.secrets === undefined ? platformSecrets(this.host, options.home) : options.secrets;
         this.now = options.now ?? Date.now;
         this.sleep = options.sleep ?? sleep;
+        this.accounts = wireAccounts({}, this.kinds());
     }
 
     async load(): Promise<void> {
-        this.stored = await readAccounts(this.path, (kind) => this.providers.get(kind), this.env, this.host);
-        this.accounts = wireAccounts(this.stored);
+        this.stored = await readAccounts(this.path, this.accountProviders(), this.env, this.host);
+        this.accounts = wireAccounts(this.stored, this.kinds());
         await this.readSecrets();
     }
 
@@ -162,7 +175,7 @@ export class ProviderAccountsService implements AccountLaunches {
 
     snapshot(): ProviderAccounts {
         const loginCommands: Partial<Record<AgentKind, string>> = {};
-        for (const kind of AgentKindSchema.options) {
+        for (const kind of this.kinds()) {
             const command = this.providers.get(kind).home?.loginCommand;
             if (command !== undefined) {
                 loginCommands[kind] = command;
@@ -206,7 +219,9 @@ export class ProviderAccountsService implements AccountLaunches {
             throw refuse('no account on it has that id');
         }
         if (account.kind !== kind) {
-            throw refuse(`it is an account of ${isKnownKind(account.kind) ? this.providers.get(account.kind).name : account.kind}, not of ${provider.name}`);
+            throw refuse(
+                `it is an account of ${isOfferedKind(account.kind, this.kinds()) ? this.providers.get(account.kind).name : account.kind}, not of ${provider.name}`
+            );
         }
         if (account.enabled === false) {
             throw refuse('it is turned off');
@@ -241,7 +256,7 @@ export class ProviderAccountsService implements AccountLaunches {
         if (fromAccount === undefined || toAccount === undefined || fromAccount.kind !== kind) {
             return false;
         }
-        return canContinue({ id: fromId, account: fromAccount }, { id: toId, account: toAccount }, (each) => this.providers.get(each), this.env);
+        return canContinue({ id: fromId, account: fromAccount }, { id: toId, account: toAccount }, this.accountProviders(), this.env);
     }
 
     labelOf(id: string): string {
@@ -355,6 +370,14 @@ export class ProviderAccountsService implements AccountLaunches {
         }
     }
 
+    private kinds(): readonly AgentKind[] {
+        return this.providers.kinds?.() ?? KNOWN_AGENT_KINDS;
+    }
+
+    private accountProviders(): AccountProviders {
+        return { kinds: this.kinds(), get: (kind) => this.providers.get(kind) };
+    }
+
     /* One change of the file at a time: a create and a save both read what the other just wrote. */
     private serial<T>(work: () => Promise<T>): Promise<T> {
         const next = this.writes.then(work);
@@ -363,7 +386,7 @@ export class ProviderAccountsService implements AccountLaunches {
     }
 
     private async commit(accounts: ProviderAccountMap, isDirectory: (path: string) => boolean): Promise<ProviderAccounts> {
-        const stored = acceptAccounts(accounts, this.stored, (kind) => this.providers.get(kind), this.env, isDirectory, this.host);
+        const stored = acceptAccounts(accounts, this.stored, this.accountProviders(), this.env, isDirectory, this.host);
         const { writes, removals } = this.planSecrets(stored);
         for (const [key, value] of writes) {
             await this.requireSecrets().write(key, value);
@@ -371,7 +394,7 @@ export class ProviderAccountsService implements AccountLaunches {
         }
         await writeAccounts(this.path, stored);
         this.stored = stored;
-        this.accounts = wireAccounts(stored);
+        this.accounts = wireAccounts(stored, this.kinds());
         for (const key of removals) {
             this.secretValues.delete(key);
             await this.secrets?.remove(key).catch((e: unknown) => console.error(`Could not remove ${key} from the keychain:`, errorText(e)));
@@ -397,7 +420,7 @@ export class ProviderAccountsService implements AccountLaunches {
         const kept = new Set<string>();
         for (const [id, entry] of Object.entries(stored)) {
             const kind = (entry as { kind: string }).kind;
-            if (!isKnownKind(kind)) {
+            if (!isOfferedKind(kind, this.kinds())) {
                 for (const name of sensitiveNames(entry)) {
                     kept.add(secretKey(id, name));
                 }
@@ -508,7 +531,7 @@ export class ProviderAccountsService implements AccountLaunches {
         state: ProviderAccountStatus['state'],
         fields: Partial<Omit<ProviderAccountStatus, 'id' | 'kind' | 'state'>> = {}
     ): ProviderAccountStatus {
-        const provider = isKnownKind(account.kind) ? this.providers.get(account.kind) : null;
+        const provider = isOfferedKind(account.kind, this.kinds()) ? this.providers.get(account.kind) : null;
         const folder = provider === null ? '' : accountFolder(id, account, provider, this.env);
         return {
             id,
@@ -555,7 +578,7 @@ export class ProviderAccountsService implements AccountLaunches {
 
     private async check(id: string, account: ProviderAccount, installed: ProviderInfo[]): Promise<ProviderAccountStatus> {
         const kind = account.kind;
-        if (!isKnownKind(kind)) {
+        if (!isOfferedKind(kind, this.kinds())) {
             return this.status(id, account, 'unavailable', { message: `This version of ${this.host.name} does not know this CLI` });
         }
         const provider = this.providers.get(kind);

package/src/providers/accounts/store.ts

@@ -11,9 +11,10 @@ import {
     expandHome,
     folderVariablesOf,
     isDefaultAccount,
-    isKnownKind,
+    isOfferedKind,
     readAccount,
     withDefaults,
+    type AccountProviders,
     type Env
 } from './accounts.ts';
 import { DEFAULT_ACCOUNTS_HOST, redactVariables, type AccountsHost } from './variables.ts';
@@ -31,12 +32,7 @@ export function accountsPath(home: string): string {
 export type StoredAccounts = Record<string, unknown>;
 
 /* Every entry that does not parse is dropped on its own; a file that is not JSON at all reads as none. */
-export async function readAccounts(
-    path: string,
-    providerOf: (kind: AgentKind) => ChatProvider,
-    env: Env,
-    host: AccountsHost = DEFAULT_ACCOUNTS_HOST
-): Promise<StoredAccounts> {
+export async function readAccounts(path: string, providers: AccountProviders, env: Env, host: AccountsHost = DEFAULT_ACCOUNTS_HOST): Promise<StoredAccounts> {
     let parsed: unknown;
     try {
         parsed = JSON.parse(await readFile(path, 'utf8'));
@@ -55,7 +51,7 @@ export async function readAccounts(
         if (!ProviderAccountIdSchema.safeParse(id).success) {
             continue;
         }
-        const account = readAccount(id, raw, providerOf, env, host);
+        const account = readAccount(id, raw, providers, env, host);
         if (account !== null) {
             stored[id] = account;
         }
@@ -76,8 +72,8 @@ function wireAccount(entry: unknown): ProviderAccount {
     return parsed.data.env === undefined ? parsed.data : { ...parsed.data, env: redactVariables(parsed.data.env) };
 }
 
-export function wireAccounts(stored: StoredAccounts): ProviderAccountMap {
-    return withDefaults(Object.fromEntries(Object.entries(stored).map(([id, entry]) => [id, wireAccount(entry)])));
+export function wireAccounts(stored: StoredAccounts, kinds: readonly AgentKind[]): ProviderAccountMap {
+    return withDefaults(Object.fromEntries(Object.entries(stored).map(([id, entry]) => [id, wireAccount(entry)])), kinds);
 }
 
 export class InvalidAccountError extends CodedError<'invalid-account'> {
@@ -130,16 +126,16 @@ function linkProblem(
 export function acceptAccounts(
     saved: ProviderAccountMap,
     before: StoredAccounts,
-    providerOf: (kind: AgentKind) => ChatProvider,
+    providers: AccountProviders,
     env: Env,
     isDirectory: (path: string) => boolean,
     host: AccountsHost = DEFAULT_ACCOUNTS_HOST
 ): StoredAccounts {
     const stored: StoredAccounts = {};
-    const reserved = { host, folderVariables: folderVariablesOf(providerOf) };
-    for (const [id, account] of Object.entries(withDefaults(saved))) {
-        if (!isKnownKind(account.kind)) {
-            if (isKnownKind(id)) {
+    const reserved = { host, folderVariables: folderVariablesOf(providers) };
+    for (const [id, account] of Object.entries(withDefaults(saved, providers.kinds))) {
+        if (!isOfferedKind(account.kind, providers.kinds)) {
+            if (isOfferedKind(id, providers.kinds)) {
                 throw new InvalidAccountError(`"${id}" is the id of the default ${id} account`);
             }
             const kept = before[id];
@@ -147,8 +143,9 @@ export function acceptAccounts(
             stored[id] = keptKind === account.kind ? kept : account;
             continue;
         }
-        const provider = providerOf(account.kind);
-        const problem = accountProblem(id, account, provider, env, reserved) ?? linkProblem(id, account, before[id], provider, env, isDirectory);
+        const provider = providers.get(account.kind);
+        const problem =
+            accountProblem(id, account, provider, env, reserved, providers.kinds) ?? linkProblem(id, account, before[id], provider, env, isDirectory);
         if (problem !== null) {
             throw new InvalidAccountError(`${id}: ${problem}`);
         }

package/src/providers/acp-provider.ts

@@ -0,0 +1,73 @@
+import type { AgentKind, ProviderCapabilities } from '@adecore/agent-contracts';
+import { createAcpBackend, type AcpAgentSpec } from '../chat/acp-backend.ts';
+import type { ModelCatalog } from './catalog.ts';
+import { detectCli, type CliDetection } from './detect.ts';
+import type { ChatProvider, ProviderHome } from './provider.ts';
+
+/*
+ * What every ACP agent can do through this backend. A file change comes as the text before and after;
+ * a message names its mentions and attachments by path, as text the agent opens with its own tools.
+ */
+export const ACP_CAPABILITIES: ProviderCapabilities = {
+    chat: true,
+    terminal: false,
+    hooks: false,
+    streamsToolOutput: false,
+    diffs: 'before-after',
+    attachments: true,
+    mentions: true,
+    denyReason: false,
+    allowAlways: true,
+    asyncQuestions: false,
+    compaction: 'none',
+    reportsCost: false,
+    reportsContextWindow: false,
+    reportsThinking: true,
+    slashCommands: true
+};
+
+/* One ACP agent as a host offers it: the backend's spec, plus what makes it a provider. */
+export interface AcpProviderSpec extends AcpAgentSpec {
+    kind: AgentKind;
+    // The executable, and the arguments that start it as an ACP agent on its stdio.
+    command: string;
+    args?: readonly string[];
+    catalog: ModelCatalog;
+    // Over `ACP_CAPABILITIES`, for an agent that reports its cost or context window, or whose commands fold its context.
+    capabilities?: Partial<ProviderCapabilities>;
+    // What a terminal runs to continue one of its sessions; empty where it has none.
+    resumeCommand?: string;
+    home?: ProviderHome;
+    ignoresProjectConfig?: boolean;
+    oneShotArgs?(prompt: string): string[];
+    oneShotStdinArgs?: readonly string[];
+    // Absent leaves the agent to chats only.
+    firstPromptArgs?(prompt: string): string[];
+    // Absent asks the executable for `--version`.
+    detect?(command: string, env: Record<string, string | undefined>): Promise<CliDetection>;
+    enabled?(): boolean;
+}
+
+export function createAcpProvider(spec: AcpProviderSpec): ChatProvider {
+    const capabilities = { ...ACP_CAPABILITIES, ...spec.capabilities };
+    return {
+        kind: spec.kind,
+        name: spec.name,
+        catalog: spec.catalog,
+        capabilities,
+        command: [spec.command, ...(spec.args ?? [])],
+        resumeCommand: spec.resumeCommand ?? '',
+        ...(spec.ignoresProjectConfig === undefined ? {} : { ignoresProjectConfig: spec.ignoresProjectConfig }),
+        ...(spec.home ? { home: spec.home } : {}),
+        ...(spec.oneShotArgs ? { oneShotArgs: spec.oneShotArgs } : {}),
+        ...(spec.oneShotStdinArgs ? { oneShotStdinArgs: spec.oneShotStdinArgs } : {}),
+        ...(spec.enabled ? { enabled: spec.enabled } : {}),
+        firstPromptArgs:
+            spec.firstPromptArgs ??
+            (() => {
+                throw new Error(`${spec.name} is only available as a chat.`);
+            }),
+        detect: spec.detect ?? ((command, env) => detectCli(command, env)),
+        createBackend: createAcpBackend(spec)
+    };
+}

package/src/providers/catalog.ts

@@ -41,6 +41,7 @@ export class ModelCatalog {
             slug: model.slug,
             name: model.name,
             badge: model.badge,
+            ...(model.vendor === undefined ? {} : { vendor: model.vendor }),
             legacy: model.legacy === true,
             isDefault: model.slug === this.data.defaultModel,
             options: this.profileOf(model.slug)?.options ?? [],