@adecore/agents 0.46.3 → 0.48.0

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

@@ -1,4 +1,4 @@
-import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatGoalAction, type ChatInfo, type ChatItem, type ChatQueuedMessage, type ChatUiChoicePayload, type ChatUiQueryPayload, type ChatUiLinkPayload, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ChatVisual, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
+import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatGoalAction, type ChatInfo, type ChatItem, type ChatNoteMessage, type ChatQueuedMessage, type ChatUiChoicePayload, type ChatUiQueryPayload, type ChatUiLinkPayload, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ChatVisual, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
 import type { AgentEvent, AgentSink } from '../events.ts';
 import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
 import { type AccountLaunches } from '../providers/accounts/launch.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<{
@@ -180,7 +182,7 @@ export declare class ChatCore {
     writeRecord(chatId: string, info: ChatInfo, items: ChatItem[], preambles?: string[]): Promise<void>;
     deleteRecord(chatId: string): Promise<boolean>;
     lastTurn(chatId: string): Promise<ChatTurnItem | null>;
-    addNote(chatId: string, level: 'info' | 'warning' | 'error', text: string): Promise<void>;
+    addNote(chatId: string, level: 'info' | 'warning' | 'error', text: string, message?: ChatNoteMessage): Promise<void>;
     deliverNote(chatId: string, delivery: {
         noteId: string;
         note: string;

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);
@@ -643,7 +648,7 @@ export class ChatCore {
         return stored?.items.findLast((item) => item.kind === 'turn') ?? null;
     }
     /* A line from the host in a chat's thread, loading the chat when nobody has; nothing for a chat that is gone. */
-    async addNote(chatId, level, text) {
+    async addNote(chatId, level, text, message) {
         await this.loaded(chatId);
         if (!(await this.hasStored(chatId))) {
             return;
@@ -651,7 +656,7 @@ export class ChatCore {
         if (!this.chats.has(chatId)) {
             await this.create({ chatId });
         }
-        this.chats.get(chatId)?.addNote(level, text);
+        this.chats.get(chatId)?.addNote(level, text, message);
     }
     /*
      * Leaves a note and its preamble in a chat, loading that chat when nobody has; false when it was

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

@@ -1,4 +1,4 @@
-import type { ChatAttachment, ChatCheckpointDiff, ChatEvent, ChatGoalAction, ChatInfo, ChatItem, ChatQueuedMessage, ChatQuoteSource, ChatSkill, ChatUiChoiceOrigin, ChatUiChoicePayload, ChatUiQueryState, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+import type { ChatAttachment, ChatCheckpointDiff, ChatEvent, ChatGoalAction, ChatInfo, ChatItem, ChatNoteMessage, ChatQueuedMessage, ChatQuoteSource, ChatSkill, ChatUiChoiceOrigin, ChatUiChoicePayload, ChatUiQueryState, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
 import type { ChatProvider } from '../providers/provider.ts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import type { BackendLaunch } from './backend.ts';
@@ -211,7 +211,7 @@ export declare class ChatSession {
         preamble: string;
     }): boolean;
     upsertItems(items: readonly ChatItem[]): void;
-    addNote(level: 'info' | 'warning' | 'error', text: string): void;
+    addNote(level: 'info' | 'warning' | 'error', text: string, message?: ChatNoteMessage): void;
     end(reason: string): void;
     restart(): Promise<void>;
     dropProcess(): Promise<void>;

package/dist/chat/chat-session.js

@@ -1057,8 +1057,18 @@ export class ChatSession {
         this.options.persistSoon();
     }
     /* A line in the thread outside any turn, for something the host has to say about work it gave up on. */
-    addNote(level, text) {
-        this.emit([this.thread.upsert({ id: newId('note'), kind: 'note', createdAt: Date.now(), turnId: null, level, text })]);
+    addNote(level, text, message) {
+        this.emit([
+            this.thread.upsert({
+                id: newId('note'),
+                kind: 'note',
+                createdAt: Date.now(),
+                turnId: null,
+                level,
+                text,
+                ...(message === undefined ? {} : { message })
+            })
+        ]);
         this.options.persist();
     }
     /*

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/messages/deliver-notice.d.ts

@@ -1,4 +1,4 @@
-import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatItem, ChatNoteMessage } from '@adecore/agent-contracts';
 import type { ChatCore } from '../chat/chat-core.ts';
 import type { Notice, NoticeStore } from './notice-store.ts';
 export interface MessageWords {
@@ -20,6 +20,7 @@ export declare function chatNoticeTargets(chats: Pick<ChatCore, 'get' | 'hasStor
 export declare function deliverToChat(store: Pick<NoticeStore, 'put'>, targets: ChatNoticeTargets, notice: Omit<Notice, 'createdAt'>): Promise<ChatDelivery>;
 export interface NoticeChat {
     has(id: string): Promise<boolean>;
-    note(id: string, text: string): Promise<void>;
+    note(id: string, text: string, message: ChatNoteMessage): Promise<void>;
 }
+export declare function noticeMessage(notice: Notice): ChatNoteMessage;
 export declare function showNotices(store: Pick<NoticeStore, 'show'>, chat: NoticeChat, words: Pick<MessageWords, 'shown'>, targetId: string): Promise<void>;

package/dist/messages/deliver-notice.js

@@ -57,6 +57,10 @@ export async function deliverToChat(store, targets, notice) {
     }
     return { outcome: 'wake', waiting };
 }
+/* The message itself on the line in the thread, so a client can draw it as said to the chat. */
+export function noticeMessage(notice) {
+    return { from: notice.from, title: notice.fromTitle, text: notice.text };
+}
 /*
  * Shows a person the message in the chat's thread the moment it lands, not when the model gets round
  * to it. An id no chat holds shows and marks nothing, so a chat that opens on it later still has all of it.
@@ -66,6 +70,6 @@ export async function showNotices(store, chat, words, targetId) {
         return;
     }
     for (const notice of await store.show(targetId)) {
-        await chat.note(targetId, words.shown(notice));
+        await chat.note(targetId, words.shown(notice), noticeMessage(notice));
     }
 }

package/dist/messages/notice-notes.d.ts

@@ -1,5 +1,6 @@
+import type { ChatNoteMessage } from '@adecore/agent-contracts';
 import type { PromptNotes } from '../chat/chat-session.ts';
-import type { MessageWords } from './deliver-notice.ts';
+import { type MessageWords } from './deliver-notice.ts';
 import type { NoticeStore } from './notice-store.ts';
 export declare class NoticeNotes implements PromptNotes {
     private readonly store;
@@ -12,4 +13,7 @@ export declare class NoticeNotes implements PromptNotes {
     };
     reset(): void;
 }
-export declare function unshownNotes(store: Pick<NoticeStore, 'show'>, chatId: string, words: Pick<MessageWords, 'shown'>): Promise<string[]>;
+export declare function unshownNotes(store: Pick<NoticeStore, 'show'>, chatId: string, words: Pick<MessageWords, 'shown'>): Promise<{
+    text: string;
+    message: ChatNoteMessage;
+}[]>;

package/dist/messages/notice-notes.js

@@ -1,3 +1,4 @@
+import { noticeMessage } from './deliver-notice.js';
 /*
  * What another node left for a chat, taken from the queue in front of its next prompt so the model
  * hears it once. Nothing of it is shown: a person read each message in the thread as it landed
@@ -22,5 +23,5 @@ export class NoticeNotes {
  * reload writes none again. The model still hears the messages themselves from the queue.
  */
 export async function unshownNotes(store, chatId, words) {
-    return (await store.show(chatId)).map((notice) => words.shown(notice));
+    return (await store.show(chatId)).map((notice) => ({ text: words.shown(notice), message: noticeMessage(notice) }));
 }

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.46.3",
+  "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.46.3",
-    "@adecore/intelligent-ui": "0.46.3",
+    "@adecore/agent-contracts": "0.48.0",
+    "@adecore/intelligent-ui": "0.48.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/src/chat/chat-core.ts

@@ -17,6 +17,7 @@ import {
     type ChatGoalAction,
     type ChatInfo,
     type ChatItem,
+    type ChatNoteMessage,
     type ChatQueuedMessage,
     type ChatUiChoicePayload,
     type ChatUiQueryPayload,
@@ -116,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. */
@@ -386,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);
     }
@@ -478,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);
@@ -625,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);
@@ -974,7 +986,7 @@ export class ChatCore {
     }
 
     /* A line from the host in a chat's thread, loading the chat when nobody has; nothing for a chat that is gone. */
-    async addNote(chatId: string, level: 'info' | 'warning' | 'error', text: string): Promise<void> {
+    async addNote(chatId: string, level: 'info' | 'warning' | 'error', text: string, message?: ChatNoteMessage): Promise<void> {
         await this.loaded(chatId);
 
         if (!(await this.hasStored(chatId))) {
@@ -985,7 +997,7 @@ export class ChatCore {
             await this.create({ chatId });
         }
 
-        this.chats.get(chatId)?.addNote(level, text);
+        this.chats.get(chatId)?.addNote(level, text, message);
     }
 
     /*

package/src/chat/chat-session.ts

@@ -6,6 +6,7 @@ import type {
     ChatGoalAction,
     ChatInfo,
     ChatItem,
+    ChatNoteMessage,
     ChatQueuedMessage,
     ChatQuoteSource,
     ChatSkill,
@@ -1470,8 +1471,18 @@ export class ChatSession {
     }
 
     /* A line in the thread outside any turn, for something the host has to say about work it gave up on. */
-    addNote(level: 'info' | 'warning' | 'error', text: string): void {
-        this.emit([this.thread.upsert({ id: newId('note'), kind: 'note', createdAt: Date.now(), turnId: null, level, text })]);
+    addNote(level: 'info' | 'warning' | 'error', text: string, message?: ChatNoteMessage): void {
+        this.emit([
+            this.thread.upsert({
+                id: newId('note'),
+                kind: 'note',
+                createdAt: Date.now(),
+                turnId: null,
+                level,
+                text,
+                ...(message === undefined ? {} : { message })
+            })
+        ]);
         this.options.persist();
     }
 

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/messages/deliver-notice.ts

@@ -1,4 +1,4 @@
-import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatItem, ChatNoteMessage } from '@adecore/agent-contracts';
 import type { ChatCore } from '../chat/chat-core.ts';
 import type { Notice, NoticeStore } from './notice-store.ts';
 
@@ -111,7 +111,12 @@ export interface NoticeChat {
     /* Whether the host holds a chat under the id, running or on disk. */
     has(id: string): Promise<boolean>;
     /* Puts a line in that chat's thread, loading the chat when nobody has. */
-    note(id: string, text: string): Promise<void>;
+    note(id: string, text: string, message: ChatNoteMessage): Promise<void>;
+}
+
+/* The message itself on the line in the thread, so a client can draw it as said to the chat. */
+export function noticeMessage(notice: Notice): ChatNoteMessage {
+    return { from: notice.from, title: notice.fromTitle, text: notice.text };
 }
 
 /*
@@ -124,6 +129,6 @@ export async function showNotices(store: Pick<NoticeStore, 'show'>, chat: Notice
     }
 
     for (const notice of await store.show(targetId)) {
-        await chat.note(targetId, words.shown(notice));
+        await chat.note(targetId, words.shown(notice), noticeMessage(notice));
     }
 }

package/src/messages/notice-notes.ts

@@ -1,5 +1,6 @@
+import type { ChatNoteMessage } from '@adecore/agent-contracts';
 import type { PromptNotes } from '../chat/chat-session.ts';
-import type { MessageWords } from './deliver-notice.ts';
+import { noticeMessage, type MessageWords } from './deliver-notice.ts';
 import type { NoticeStore } from './notice-store.ts';
 
 /*
@@ -29,6 +30,10 @@ export class NoticeNotes implements PromptNotes {
  * The lines a chat that just loaded owes a person for what landed while nobody held it, marked so a
  * reload writes none again. The model still hears the messages themselves from the queue.
  */
-export async function unshownNotes(store: Pick<NoticeStore, 'show'>, chatId: string, words: Pick<MessageWords, 'shown'>): Promise<string[]> {
-    return (await store.show(chatId)).map((notice) => words.shown(notice));
+export async function unshownNotes(
+    store: Pick<NoticeStore, 'show'>,
+    chatId: string,
+    words: Pick<MessageWords, 'shown'>
+): Promise<{ text: string; message: ChatNoteMessage }[]> {
+    return (await store.show(chatId)).map((notice) => ({ text: words.shown(notice), message: noticeMessage(notice) }));
 }

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';