Accounts

An account is one config folder of a CLI, passed through the variable the CLI reads it from. The person signs in with the CLI itself. @adecore/agents keeps the accounts, and the providers pane edits them.

import { ProviderAccountsSchema, topAccountOf, type ProviderAccount } from '@adecore/agent-contracts/provider-accounts';

The record

ProviderAccountIdSchema (ProviderAccountId) is a slug: a lowercase letter, then up to 63 lowercase letters, digits, underscores or hyphens. It is never a path. No account, or an id equal to the provider's kind, means the default account.

ProviderAccount (ProviderAccountSchema) is { kind, label?, color?, enabled?, home?, shadowHome?, env?, order? }. Absent enabled is on. order is the account's place among the accounts of its CLI, lowest first. home is the config folder (~ allowed), absent on the default account. shadowHome is Codex only: a separate login folder that shares everything else with home. kind is a plain string, so records of unknown CLIs still parse and round-trip. ProviderAccountMap (ProviderAccountMapSchema) holds the accounts by id.

ProviderAccountVariable (ProviderAccountVariableSchema) is { name, value, sensitive, valueRedacted? }, a variable the host sets in the CLI's environment. The host never sends a sensitive value. It sends value: '' with valueRedacted: true, and saving that back keeps the stored secret.

Order

orderedAccountIds(accounts, kind) returns the ids of one CLI's accounts in the person's order: by order, then the default account, then the rest by id. A machine where nobody reordered keeps the default account on top. topAccountOf(accounts, kind) returns the account a start takes when nothing names one: the first in that order that is on, or else the CLI's default account.

const accounts = ProviderAccountsSchema.parse(snapshot).accounts;
const startOn = topAccountOf(accounts, 'codex');

Status

ProviderAccountStatus (ProviderAccountStatusSchema) is the CLI's last answer about an account, never stored. Its state is a ProviderAccountState (ProviderAccountStateSchema): checking, disabled, not-found, signed-out, ready, folder-missing, unavailable or failed. It has optional email, plan, organization and message. transcripts is where the account writes conversations. A chat can move only between accounts that share it.

Requests

ProviderAccounts (ProviderAccountsSchema) is the snapshot that most account requests answer with, and that accounts.changed carries: accounts, statuses, secretsAvailable?, loginCommands? (the terminal sign-in command per CLI) and chatLogins? (kinds that sign in from a chat). secretsAvailable says whether the host can store secrets.

Request	Payload and answer
accounts.list	The snapshot.
accounts.save	The whole map. A missing id is removed, and its folder stays. An account saved without order keeps the one it had.
accounts.reorder	{ kind, ids }: the accounts of one CLI in a person's order. An account of that CLI left out follows in the order it had; an id of another CLI or one the host does not have is refused.
accounts.create	{ kind, label, color? }, with a trimmed label of 1 to 80 characters. Returns the snapshot and the new id.
accounts.refresh	Asks every CLI again and answers when all did.
accounts.watchLogin	{ id }. Answers at once, then polls the CLI until the account is signed in.

Requests and events names the schema of each payload and answer.