@adecore/agents 0.47.0 → 0.48.0

package/dist/chat/chat-core.d.ts

@@ -26,6 +26,7 @@ export interface InterruptedRun {
 export interface ChatCoreHooks {
     admit?(chatId: string, cwd: string): Promise<void>;
     openingSelection?(chatId: string, kind: AgentKind): ModelSelection | undefined;
+    openingAccount?(chatId: string, kind: AgentKind, named: string | undefined): string | undefined;
     runtimeModeFor?(chatId: string, mode: RuntimeMode): RuntimeMode;
     instructionsFor?(chatId: string): string | null;
     resumeNoteFor?(chatId: string): string | null;
@@ -131,6 +132,7 @@ export declare class ChatCore {
     codexProcess(info: Pick<ChatInfo, 'cwd' | 'account'>): CodexProcessSpec;
     claudeProjectsDirOf(info: Pick<ChatInfo, 'account'>): string;
     canContinue(kind: AgentKind, from: string | undefined, to: string | undefined): boolean;
+    openingAccount(chatId: string, kind: AgentKind, named: string | undefined): string | undefined;
     requireAccount(kind: AgentKind, account: string | undefined): void;
     accountLabel(kind: AgentKind, account: string | undefined): string;
     readChat(chatId: string): Promise<{

package/dist/chat/chat-core.js

@@ -185,6 +185,10 @@ export class ChatCore {
         return this.accounts?.canContinue(kind, from, to) ?? false;
     }
     /* Throws for an account a CLI of this kind cannot start under on this machine. */
+    /* The account a start names, after the host had its say; with no account named, the top account of the CLI that is on. */
+    openingAccount(chatId, kind, named) {
+        return this.hooks.openingAccount?.(chatId, kind, named) ?? named ?? this.accounts?.defaultFor?.(kind);
+    }
     requireAccount(kind, account) {
         launchEnv(this.accounts, kind, account, this.env);
     }
@@ -257,9 +261,9 @@ export class ChatCore {
         const cwd = stored?.info.cwd ?? payload.cwd ?? homeFolder(this.env);
         await this.hooks.admit?.(payload.chatId, cwd);
         // A thread on disk keeps its account too. One it lost still opens, and says why on its next turn.
-        // A new one without an account takes the person's pick for this CLI, which is refused rather than replaced when it went.
-        // The pick is checked as named, before the default account loses its id, so one that is turned off is refused too.
-        const requested = payload.account ?? this.composerPreferences.for(kind).account;
+        // A new one without an account takes the host's choice, else the top account of this CLI that is on.
+        // It is checked as named, before the default account loses its id, so one that is turned off is refused too.
+        const requested = stored ? undefined : this.openingAccount(payload.chatId, kind, payload.account);
         if (!stored) {
             this.requireAccount(kind, requested);
         }
@@ -377,7 +381,8 @@ export class ChatCore {
         if (to === from) {
             return;
         }
-        // As named, so a switch to the default account is refused while it is turned off.
+        // As named, so a switch to the default account is refused while it is turned off, and one the host turned off for this chat too.
+        this.hooks.openingAccount?.(session.id, kind, requested);
         this.requireAccount(kind, requested);
         if (holdsConversation(session.info) && !this.canContinue(kind, from, to)) {
             const label = this.accountLabel(kind, to);

package/dist/chat/composer-preferences.d.ts

@@ -2,7 +2,6 @@ import type { AgentKind, ChatPreferencesPayload, ModelSelection, RuntimeMode } f
 export interface ComposerPreference {
     runtimeMode?: RuntimeMode;
     selection?: ModelSelection;
-    account?: string;
 }
 export declare class ComposerPreferences {
     private readonly byClient;

package/dist/chat/composer-preferences.js

@@ -23,10 +23,10 @@ export class ComposerPreferences {
         if (newest === null) {
             return {};
         }
-        const { runtimeMode, selections, accounts } = newest.preference;
+        // The accounts an older client still sends are left out: the order of the accounts decides where a start goes.
+        const { runtimeMode, selections } = newest.preference;
         const selection = selections?.[provider];
-        const account = accounts?.[provider];
-        return { ...(runtimeMode ? { runtimeMode } : {}), ...(selection ? { selection } : {}), ...(account ? { account } : {}) };
+        return { ...(runtimeMode ? { runtimeMode } : {}), ...(selection ? { selection } : {}) };
     }
     newest() {
         let newest = null;

package/dist/host/handlers.js

@@ -101,6 +101,7 @@ export function accountHandlers(accounts) {
     return {
         'accounts.list': () => accounts.snapshot(),
         'accounts.save': (payload) => accounts.save(payload.accounts),
+        'accounts.reorder': (payload) => accounts.reorder(payload.kind, payload.ids),
         'accounts.refresh': () => accounts.refresh(),
         'accounts.create': (payload) => accounts.create(payload),
         'accounts.watchLogin': (payload) => {

package/dist/providers/accounts/choose.d.ts

@@ -0,0 +1,18 @@
+import { type AgentKind, type ProviderAccountMap } from '@adecore/agent-contracts';
+export type AccountUnusable = 'turned off on this machine' | 'signed out' | 'at its usage limit' | 'not available on this machine';
+export interface AccountChoiceInput {
+    kind: AgentKind;
+    accounts: ProviderAccountMap;
+    named: string | undefined;
+    preferred: string | undefined;
+    off: readonly string[];
+    unusable(id: string): AccountUnusable | null;
+}
+export interface ChosenAccount {
+    account: string;
+    passedOver?: {
+        account: string;
+        reason: AccountUnusable;
+    };
+}
+export declare function chooseAccount(input: AccountChoiceInput): ChosenAccount;

package/dist/providers/accounts/choose.js

@@ -0,0 +1,27 @@
+import { orderedAccountIds } from '@adecore/agent-contracts';
+import { AccountError } from './launch.js';
+/*
+ * The account a start takes: a named one unless the place turned it off, which refuses the start; else
+ * the preferred one while it is usable; else the first usable account in the person's order that the
+ * place offers; else the CLI's default account, which the launch refuses as before when it cannot run.
+ */
+export function chooseAccount(input) {
+    const { kind, accounts, named, preferred, off } = input;
+    if (named !== undefined) {
+        if (off.includes(named)) {
+            throw new AccountError('account-off-in-project', `The account '${named}' is turned off in this project.`);
+        }
+        return { account: named };
+    }
+    const offered = orderedAccountIds(accounts, kind).filter((id) => !off.includes(id));
+    const known = preferred !== undefined && offered.includes(preferred) ? preferred : undefined;
+    const reason = known === undefined ? null : input.unusable(known);
+    if (known !== undefined && reason === null) {
+        return { account: known };
+    }
+    const next = offered.find((id) => id !== known && input.unusable(id) === null) ?? kind;
+    if (off.includes(next)) {
+        throw new AccountError('account-off-in-project', 'No account this project offers can start right now.');
+    }
+    return known === undefined || reason === null ? { account: next } : { account: next, passedOver: { account: known, reason } };
+}

package/dist/providers/accounts/launch.d.ts

@@ -1,7 +1,7 @@
 import type { AgentKind } from '@adecore/agent-contracts';
 import { CodedError } from '../../coded-error.ts';
 import type { Env } from './accounts.ts';
-export declare class AccountError extends CodedError<'account-unavailable' | 'account-incompatible'> {
+export declare class AccountError extends CodedError<'account-unavailable' | 'account-incompatible' | 'account-off-in-project'> {
 }
 export interface AccountLaunches {
     envFor(kind: AgentKind, account: string | undefined, baseEnv: Env): Env;
@@ -10,6 +10,7 @@ export interface AccountLaunches {
     canContinue(kind: AgentKind, from: string | undefined, to: string | undefined): boolean;
     labelOf(account: string): string;
     launched?(kind: AgentKind, account: string | undefined): void;
+    defaultFor?(kind: AgentKind): string;
 }
 export declare function isDefaultAccountOf(kind: AgentKind, account: string | undefined): boolean;
 export declare function storedAccount(kind: AgentKind, account: string | undefined): string | undefined;

package/dist/providers/accounts/service.d.ts

@@ -67,6 +67,8 @@ export declare class ProviderAccountsService implements AccountLaunches {
     start(): void;
     stop(): void;
     save(accounts: ProviderAccountMap): Promise<ProviderAccounts>;
+    defaultFor(kind: AgentKind): string;
+    reorder(kind: AgentKind, ids: readonly string[]): Promise<ProviderAccounts>;
     create(payload: ProviderAccountCreatePayload): Promise<ProviderAccountCreateResult>;
     watchLogin(id: string): Promise<void>;
     refresh(): Promise<ProviderAccounts>;

package/dist/providers/accounts/service.js

@@ -1,7 +1,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { KNOWN_AGENT_KINDS } from '@adecore/agent-contracts';
+import { KNOWN_AGENT_KINDS, topAccountOf } from '@adecore/agent-contracts';
 import { DEFAULT_CODEX_CLIENT } from '../../chat/codex-transport.js';
 import { ClientSinks } from '../../client-sinks.js';
 import { errorText } from '../../error-text.js';
@@ -10,7 +10,7 @@ import { accountEnv, accountFolder, canContinue, defaultFolder, expandHome, isDe
 import { AccountError, isDefaultAccountOf } from './launch.js';
 import { prepareShadowHome } from './shadow-home.js';
 import { ASKED_KINDS, askAccountAs } from './status.js';
-import { acceptAccounts, accountsPath, InvalidAccountError, readAccounts, wireAccounts, writeAccounts } from './store.js';
+import { acceptAccounts, accountsPath, InvalidAccountError, readAccounts, reorderedAccounts, wireAccounts, writeAccounts } from './store.js';
 import { DEFAULT_ACCOUNTS_HOST, platformSecrets, secretKey, SecretsUnavailableError } from './variables.js';
 /* Who is signed in changes by hand and rarely; often enough to notice, rarely enough not to start CLIs all day. */
 const CHECK_INTERVAL_MS = 15 * 60_000;
@@ -232,6 +232,13 @@ export class ProviderAccountsService {
     save(accounts) {
         return this.writes.run(() => this.commit(accounts, this.folderExists));
     }
+    defaultFor(kind) {
+        return topAccountOf(this.accounts, kind);
+    }
+    /* Puts the accounts of one CLI in this order; an id of another CLI or one this machine does not have refuses it. */
+    reorder(kind, ids) {
+        return this.writes.run(() => this.commit(reorderedAccounts(this.accounts, kind, ids), this.folderExists, true));
+    }
     /*
      * An account in a folder of its own under `<home>/accounts`, signed in by nobody yet. A
      * Codex account is a shadow home over the CLI's own folder, so its threads go on under the other.
@@ -305,8 +312,8 @@ export class ProviderAccountsService {
     accountProviders() {
         return { kinds: this.kinds(), get: (kind) => this.providers.get(kind) };
     }
-    async commit(accounts, isDirectory) {
-        const stored = acceptAccounts(accounts, this.stored, this.accountProviders(), this.env, isDirectory, this.host);
+    async commit(accounts, isDirectory, takeOrder = false) {
+        const stored = acceptAccounts(accounts, this.stored, this.accountProviders(), this.env, isDirectory, this.host, takeOrder);
         const { writes, removals } = this.planSecrets(stored);
         for (const [key, value] of writes) {
             await this.requireSecrets().write(key, value);

package/dist/providers/accounts/store.d.ts

@@ -10,4 +10,5 @@ export declare function wireAccounts(stored: StoredAccounts, kinds: readonly Age
 export declare class InvalidAccountError extends CodedError<'invalid-account'> {
     constructor(message: string);
 }
-export declare function acceptAccounts(saved: ProviderAccountMap, before: StoredAccounts, providers: AccountProviders, env: Env, isDirectory: (path: string) => boolean, host?: AccountsHost): StoredAccounts;
+export declare function acceptAccounts(saved: ProviderAccountMap, before: StoredAccounts, providers: AccountProviders, env: Env, isDirectory: (path: string) => boolean, host?: AccountsHost, takeOrder?: boolean): StoredAccounts;
+export declare function reorderedAccounts(accounts: ProviderAccountMap, kind: AgentKind, ids: readonly string[]): ProviderAccountMap;

package/dist/providers/accounts/store.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ProviderAccountIdSchema, ProviderAccountSchema } from '@adecore/agent-contracts';
+import { orderedAccountIds, ProviderAccountIdSchema, ProviderAccountSchema } from '@adecore/agent-contracts';
 import { CodedError } from '../../coded-error.js';
 import { isNotFound, writeAtomic } from '../../fs.js';
 import { accountFolder, accountProblem, defaultFolder, expandHome, folderVariablesOf, isDefaultAccount, isOfferedKind, readAccount, withDefaults } from './accounts.js';
@@ -88,7 +88,9 @@ function linkProblem(id, account, before, provider, env, isDirectory) {
  * client that knows the kind no better than this host could only have cut short. Sensitive values
  * are still in it: the caller puts them in the keychain before the file is written.
  */
-export function acceptAccounts(saved, before, providers, env, isDirectory, host = DEFAULT_ACCOUNTS_HOST) {
+export function acceptAccounts(saved, before, providers, env, isDirectory, host = DEFAULT_ACCOUNTS_HOST, 
+// Only `accounts.reorder` takes the order it is given.
+takeOrder = false) {
     const stored = {};
     const reserved = { host, folderVariables: folderVariablesOf(providers) };
     for (const [id, account] of Object.entries(withDefaults(saved, providers.kinds))) {
@@ -106,7 +108,37 @@ export function acceptAccounts(saved, before, providers, env, isDirectory, host
         if (problem !== null) {
             throw new InvalidAccountError(`${id}: ${problem}`);
         }
-        stored[id] = account;
+        stored[id] = takeOrder ? account : withKeptOrder(account, before[id]);
     }
     return stored;
 }
+/*
+ * Only `accounts.reorder` moves an account, so a save keeps the place the file has: an older client
+ * strips `order`, and a newer one may send the order it read before a reorder elsewhere.
+ */
+function withKeptOrder(account, before) {
+    const { order: _sent, ...rest } = account;
+    const order = typeof before === 'object' && before !== null ? before.order : undefined;
+    return typeof order === 'number' ? { ...rest, order } : rest;
+}
+/* The map with the accounts of one CLI in this order; one of that CLI not named, such as one made meanwhile, follows in the order it had. */
+export function reorderedAccounts(accounts, kind, ids) {
+    if (new Set(ids).size !== ids.length) {
+        throw new InvalidAccountError('an account is named twice in the order');
+    }
+    for (const id of ids) {
+        const account = accounts[id];
+        if (account === undefined) {
+            throw new InvalidAccountError(`${id}: no account on this machine has that id`);
+        }
+        if (account.kind !== kind) {
+            throw new InvalidAccountError(`${id}: it is an account of ${account.kind}, not of ${kind}`);
+        }
+    }
+    const order = [...ids, ...orderedAccountIds(accounts, kind).filter((id) => !ids.includes(id))];
+    const reordered = { ...accounts };
+    for (const [place, id] of order.entries()) {
+        reordered[id] = { ...accounts[id], order: place };
+    }
+    return reordered;
+}

package/dist/providers/index.d.ts

@@ -1,6 +1,7 @@
 export { type AcpCatalogStore } from './acp-agent-state.ts';
 export { ACP_CAPABILITIES, type AcpProviderSpec, createAcpProvider } from './acp-provider.ts';
 export { type AcpAccountProbe, askAcpAccount, type ProbeTimer } from './accounts/acp-account.ts';
+export { chooseAccount, type AccountChoiceInput, type AccountUnusable, type ChosenAccount } from './accounts/choose.ts';
 export { AccountError, type AccountLaunches, storedAccount, launchEnv } from './accounts/launch.ts';
 export { ProviderAccountsService, type ProviderAccountsOptions } from './accounts/service.ts';
 export type { ShadowHomeReport } from './accounts/shadow-home.ts';

package/dist/providers/index.js

@@ -2,6 +2,7 @@
 export {} from './acp-agent-state.js';
 export { ACP_CAPABILITIES, createAcpProvider } from './acp-provider.js';
 export { askAcpAccount } from './accounts/acp-account.js';
+export { chooseAccount } from './accounts/choose.js';
 export { AccountError, storedAccount, launchEnv } from './accounts/launch.js';
 export { ProviderAccountsService } from './accounts/service.js';
 export { variablesProblem, keychainService } from './accounts/variables.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -93,8 +93,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.47.0",
-    "@adecore/intelligent-ui": "0.47.0",
+    "@adecore/agent-contracts": "0.48.0",
+    "@adecore/intelligent-ui": "0.48.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/src/chat/chat-core.ts

@@ -117,6 +117,11 @@ export interface ChatCoreHooks {
     admit?(chatId: string, cwd: string): Promise<void>;
     /* The model a new chat starts on when the host already knows; the explicit one still wins. */
     openingSelection?(chatId: string, kind: AgentKind): ModelSelection | undefined;
+    /*
+     * The account a new chat starts under, given the one its start named (undefined for none);
+     * undefined leaves it to the order of the accounts. Throws an `AccountError` to refuse the start.
+     */
+    openingAccount?(chatId: string, kind: AgentKind, named: string | undefined): string | undefined;
     /* The mode a chat runs in, which a host may narrow whatever its record or its client says. */
     runtimeModeFor?(chatId: string, mode: RuntimeMode): RuntimeMode;
     /* What the agent is told once at the start of every process of this chat, in place of `instructions`; null for nothing. */
@@ -387,6 +392,11 @@ export class ChatCore {
     }
 
     /* Throws for an account a CLI of this kind cannot start under on this machine. */
+    /* The account a start names, after the host had its say; with no account named, the top account of the CLI that is on. */
+    openingAccount(chatId: string, kind: AgentKind, named: string | undefined): string | undefined {
+        return this.hooks.openingAccount?.(chatId, kind, named) ?? named ?? this.accounts?.defaultFor?.(kind);
+    }
+
     requireAccount(kind: AgentKind, account: string | undefined): void {
         launchEnv(this.accounts, kind, account, this.env);
     }
@@ -479,9 +489,9 @@ export class ChatCore {
         const cwd = stored?.info.cwd ?? payload.cwd ?? homeFolder(this.env);
         await this.hooks.admit?.(payload.chatId, cwd);
         // A thread on disk keeps its account too. One it lost still opens, and says why on its next turn.
-        // A new one without an account takes the person's pick for this CLI, which is refused rather than replaced when it went.
-        // The pick is checked as named, before the default account loses its id, so one that is turned off is refused too.
-        const requested = payload.account ?? this.composerPreferences.for(kind).account;
+        // A new one without an account takes the host's choice, else the top account of this CLI that is on.
+        // It is checked as named, before the default account loses its id, so one that is turned off is refused too.
+        const requested = stored ? undefined : this.openingAccount(payload.chatId, kind, payload.account);
 
         if (!stored) {
             this.requireAccount(kind, requested);
@@ -626,7 +636,8 @@ export class ChatCore {
             return;
         }
 
-        // As named, so a switch to the default account is refused while it is turned off.
+        // As named, so a switch to the default account is refused while it is turned off, and one the host turned off for this chat too.
+        this.hooks.openingAccount?.(session.id, kind, requested);
         this.requireAccount(kind, requested);
         if (holdsConversation(session.info) && !this.canContinue(kind, from, to)) {
             const label = this.accountLabel(kind, to);

package/src/chat/composer-preferences.ts

@@ -3,8 +3,6 @@ import type { AgentKind, ChatPreferencesPayload, ModelSelection, RuntimeMode } f
 export interface ComposerPreference {
     runtimeMode?: RuntimeMode;
     selection?: ModelSelection;
-    // The account a new chat or agent of this CLI starts under when nothing names one.
-    account?: string;
 }
 
 interface Held {
@@ -44,11 +42,11 @@ export class ComposerPreferences {
             return {};
         }
 
-        const { runtimeMode, selections, accounts } = newest.preference;
+        // The accounts an older client still sends are left out: the order of the accounts decides where a start goes.
+        const { runtimeMode, selections } = newest.preference;
         const selection = selections?.[provider];
-        const account = accounts?.[provider];
 
-        return { ...(runtimeMode ? { runtimeMode } : {}), ...(selection ? { selection } : {}), ...(account ? { account } : {}) };
+        return { ...(runtimeMode ? { runtimeMode } : {}), ...(selection ? { selection } : {}) };
     }
 
     private newest(): Held | null {

package/src/host/handlers.ts

@@ -150,6 +150,7 @@ export function accountHandlers(accounts: ProviderAccountsService): { [T in Acco
     return {
         'accounts.list': () => accounts.snapshot(),
         'accounts.save': (payload) => accounts.save(payload.accounts),
+        'accounts.reorder': (payload) => accounts.reorder(payload.kind, payload.ids),
         'accounts.refresh': () => accounts.refresh(),
         'accounts.create': (payload) => accounts.create(payload),
         'accounts.watchLogin': (payload) => {

package/src/providers/accounts/choose.ts

@@ -0,0 +1,57 @@
+import { orderedAccountIds, type AgentKind, type ProviderAccountMap } from '@adecore/agent-contracts';
+import { AccountError } from './launch.ts';
+
+/* Why an account cannot take a start right now, in words that finish "is ...". */
+export type AccountUnusable = 'turned off on this machine' | 'signed out' | 'at its usage limit' | 'not available on this machine';
+
+export interface AccountChoiceInput {
+    kind: AgentKind;
+    accounts: ProviderAccountMap;
+    /* The account the start named; undefined for none. */
+    named: string | undefined;
+    /* The account the place of the start prefers, such as a project's default. */
+    preferred: string | undefined;
+    /* The accounts the place of the start never offers. */
+    off: readonly string[];
+    /* Why an account cannot take a start right now, or null when it can. */
+    unusable(id: string): AccountUnusable | null;
+}
+
+export interface ChosenAccount {
+    account: string;
+    /* The preferred account the start passed over, and why; absent when it took that one or none was preferred. */
+    passedOver?: { account: string; reason: AccountUnusable };
+}
+
+/*
+ * The account a start takes: a named one unless the place turned it off, which refuses the start; else
+ * the preferred one while it is usable; else the first usable account in the person's order that the
+ * place offers; else the CLI's default account, which the launch refuses as before when it cannot run.
+ */
+export function chooseAccount(input: AccountChoiceInput): ChosenAccount {
+    const { kind, accounts, named, preferred, off } = input;
+
+    if (named !== undefined) {
+        if (off.includes(named)) {
+            throw new AccountError('account-off-in-project', `The account '${named}' is turned off in this project.`);
+        }
+
+        return { account: named };
+    }
+
+    const offered = orderedAccountIds(accounts, kind).filter((id) => !off.includes(id));
+    const known = preferred !== undefined && offered.includes(preferred) ? preferred : undefined;
+    const reason = known === undefined ? null : input.unusable(known);
+
+    if (known !== undefined && reason === null) {
+        return { account: known };
+    }
+
+    const next = offered.find((id) => id !== known && input.unusable(id) === null) ?? kind;
+
+    if (off.includes(next)) {
+        throw new AccountError('account-off-in-project', 'No account this project offers can start right now.');
+    }
+
+    return known === undefined || reason === null ? { account: next } : { account: next, passedOver: { account: known, reason } };
+}

package/src/providers/accounts/launch.ts

@@ -2,7 +2,7 @@ import type { AgentKind } from '@adecore/agent-contracts';
 import { CodedError } from '../../coded-error.ts';
 import type { Env } from './accounts.ts';
 
-export class AccountError extends CodedError<'account-unavailable' | 'account-incompatible'> {}
+export class AccountError extends CodedError<'account-unavailable' | 'account-incompatible' | 'account-off-in-project'> {}
 
 /*
  * The accounts as a terminal or a chat starts a CLI under one. Absent, or the CLI's own kind, is the
@@ -21,6 +21,8 @@ export interface AccountLaunches {
     labelOf(account: string): string;
     /* A CLI started under this account a moment ago, which is what keeps its plan read. */
     launched?(kind: AgentKind, account: string | undefined): void;
+    /* The account a start of this CLI takes when nothing names one: the top one in the person's order that is on. */
+    defaultFor?(kind: AgentKind): string;
 }
 
 export function isDefaultAccountOf(kind: AgentKind, account: string | undefined): boolean {

package/src/providers/accounts/service.ts

@@ -3,6 +3,7 @@ import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import {
     KNOWN_AGENT_KINDS,
+    topAccountOf,
     type AgentKind,
     type ProviderAccount,
     type ProviderAccountCreatePayload,
@@ -34,7 +35,16 @@ import {
 import { AccountError, isDefaultAccountOf, type AccountLaunches } from './launch.ts';
 import { prepareShadowHome, type ShadowHomeReport } from './shadow-home.ts';
 import { ASKED_KINDS, askAccountAs, type AskAccount } from './status.ts';
-import { acceptAccounts, accountsPath, InvalidAccountError, readAccounts, wireAccounts, writeAccounts, type StoredAccounts } from './store.ts';
+import {
+    acceptAccounts,
+    accountsPath,
+    InvalidAccountError,
+    readAccounts,
+    reorderedAccounts,
+    wireAccounts,
+    writeAccounts,
+    type StoredAccounts
+} from './store.ts';
 import { DEFAULT_ACCOUNTS_HOST, platformSecrets, secretKey, SecretsUnavailableError, type AccountsHost, type SecretStore } from './variables.ts';
 
 /* Who is signed in changes by hand and rarely; often enough to notice, rarely enough not to start CLIs all day. */
@@ -343,6 +353,15 @@ export class ProviderAccountsService implements AccountLaunches {
         return this.writes.run(() => this.commit(accounts, this.folderExists));
     }
 
+    defaultFor(kind: AgentKind): string {
+        return topAccountOf(this.accounts, kind);
+    }
+
+    /* Puts the accounts of one CLI in this order; an id of another CLI or one this machine does not have refuses it. */
+    reorder(kind: AgentKind, ids: readonly string[]): Promise<ProviderAccounts> {
+        return this.writes.run(() => this.commit(reorderedAccounts(this.accounts, kind, ids), this.folderExists, true));
+    }
+
     /*
      * An account in a folder of its own under `<home>/accounts`, signed in by nobody yet. A
      * Codex account is a shadow home over the CLI's own folder, so its threads go on under the other.
@@ -437,8 +456,8 @@ export class ProviderAccountsService implements AccountLaunches {
         return { kinds: this.kinds(), get: (kind) => this.providers.get(kind) };
     }
 
-    private async commit(accounts: ProviderAccountMap, isDirectory: (path: string) => boolean): Promise<ProviderAccounts> {
-        const stored = acceptAccounts(accounts, this.stored, this.accountProviders(), this.env, isDirectory, this.host);
+    private async commit(accounts: ProviderAccountMap, isDirectory: (path: string) => boolean, takeOrder = false): Promise<ProviderAccounts> {
+        const stored = acceptAccounts(accounts, this.stored, this.accountProviders(), this.env, isDirectory, this.host, takeOrder);
         const { writes, removals } = this.planSecrets(stored);
 
         for (const [key, value] of writes) {

package/src/providers/accounts/store.ts

@@ -1,6 +1,13 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ProviderAccountIdSchema, ProviderAccountSchema, type AgentKind, type ProviderAccount, type ProviderAccountMap } from '@adecore/agent-contracts';
+import {
+    orderedAccountIds,
+    ProviderAccountIdSchema,
+    ProviderAccountSchema,
+    type AgentKind,
+    type ProviderAccount,
+    type ProviderAccountMap
+} from '@adecore/agent-contracts';
 import { CodedError } from '../../coded-error.ts';
 import { isNotFound, writeAtomic } from '../../fs.ts';
 import type { ChatProvider } from '../provider.ts';
@@ -146,7 +153,9 @@ export function acceptAccounts(
     providers: AccountProviders,
     env: Env,
     isDirectory: (path: string) => boolean,
-    host: AccountsHost = DEFAULT_ACCOUNTS_HOST
+    host: AccountsHost = DEFAULT_ACCOUNTS_HOST,
+    // Only `accounts.reorder` takes the order it is given.
+    takeOrder = false
 ): StoredAccounts {
     const stored: StoredAccounts = {};
     const reserved = { host, folderVariables: folderVariablesOf(providers) };
@@ -173,8 +182,47 @@ export function acceptAccounts(
             throw new InvalidAccountError(`${id}: ${problem}`);
         }
 
-        stored[id] = account;
+        stored[id] = takeOrder ? account : withKeptOrder(account, before[id]);
     }
 
     return stored;
 }
+
+/*
+ * Only `accounts.reorder` moves an account, so a save keeps the place the file has: an older client
+ * strips `order`, and a newer one may send the order it read before a reorder elsewhere.
+ */
+function withKeptOrder(account: ProviderAccount, before: unknown): ProviderAccount {
+    const { order: _sent, ...rest } = account;
+    const order = typeof before === 'object' && before !== null ? (before as { order?: unknown }).order : undefined;
+
+    return typeof order === 'number' ? { ...rest, order } : rest;
+}
+
+/* The map with the accounts of one CLI in this order; one of that CLI not named, such as one made meanwhile, follows in the order it had. */
+export function reorderedAccounts(accounts: ProviderAccountMap, kind: AgentKind, ids: readonly string[]): ProviderAccountMap {
+    if (new Set(ids).size !== ids.length) {
+        throw new InvalidAccountError('an account is named twice in the order');
+    }
+
+    for (const id of ids) {
+        const account = accounts[id];
+
+        if (account === undefined) {
+            throw new InvalidAccountError(`${id}: no account on this machine has that id`);
+        }
+
+        if (account.kind !== kind) {
+            throw new InvalidAccountError(`${id}: it is an account of ${account.kind}, not of ${kind}`);
+        }
+    }
+
+    const order = [...ids, ...orderedAccountIds(accounts, kind).filter((id) => !ids.includes(id))];
+    const reordered: ProviderAccountMap = { ...accounts };
+
+    for (const [place, id] of order.entries()) {
+        reordered[id] = { ...accounts[id], order: place } as ProviderAccount;
+    }
+
+    return reordered;
+}

package/src/providers/index.ts

@@ -2,6 +2,7 @@
 export { type AcpCatalogStore } from './acp-agent-state.ts';
 export { ACP_CAPABILITIES, type AcpProviderSpec, createAcpProvider } from './acp-provider.ts';
 export { type AcpAccountProbe, askAcpAccount, type ProbeTimer } from './accounts/acp-account.ts';
+export { chooseAccount, type AccountChoiceInput, type AccountUnusable, type ChosenAccount } from './accounts/choose.ts';
 export { AccountError, type AccountLaunches, storedAccount, launchEnv } from './accounts/launch.ts';
 export { ProviderAccountsService, type ProviderAccountsOptions } from './accounts/service.ts';
 export type { ShadowHomeReport } from './accounts/shadow-home.ts';