@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/providers/accounts/shadow-home.ts

@@ -0,0 +1,85 @@
+import { lstat, mkdir, readdir, readlink, symlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { isNotFound } from '../../fs.ts';
+
+/*
+ * A Codex shadow home: a folder of its own for one login, sharing everything else with a Codex home
+ * by symlink, so two accounts continue each other's threads. Codex needs its login in `auth.json`
+ * (`cli_auth_credentials_store = "file"`) for this; a login in the keychain has no folder to be in.
+ */
+
+/* Made in the shared home before anything is linked, so the first thread of either account already lands there. */
+const SHARED_FOLDERS = ['sessions', 'archived_sessions', 'skills', 'rules'];
+
+/* The login, which is the whole point of the shadow home. */
+const PRIVATE_ENTRIES = new Set(['auth.json']);
+
+/*
+ * What one Codex process keeps for itself: what the models of this login are, caches, logs, and the
+ * sockets of an app-server that answers for the account that started it.
+ */
+const LOCAL_ENTRIES = new Set(['models_cache.json', 'cache', 'log', 'logs', 'tmp', '.tmp', 'app-server-daemon', 'app-server-control', 'ipc']);
+
+/* A SQLite journal comes and goes with its database, so a link to one would soon point at nothing. */
+function isJournal(name: string): boolean {
+    return /-(wal|shm|journal)$/.test(name);
+}
+
+export interface ShadowHomeReport {
+    linked: string[];
+    // Entries of the shadow home in the way of a link: a real file or a link somewhere else. Left alone.
+    unshared: string[];
+    // A private entry that is a link, so this account would sign in as another one.
+    sharedLogin: boolean;
+}
+
+export class ShadowHomeError extends Error {}
+
+type Existing = { kind: 'missing' } | { kind: 'link'; target: string } | { kind: 'real' };
+
+async function existing(path: string): Promise<Existing> {
+    try {
+        const stats = await lstat(path);
+        return stats.isSymbolicLink() ? { kind: 'link', target: await readlink(path) } : { kind: 'real' };
+    } catch (e) {
+        if (isNotFound(e)) {
+            return { kind: 'missing' };
+        }
+        throw e;
+    }
+}
+
+/*
+ * Links every shared entry of `home` into `shadow` that is not there yet. Never overwrites and never
+ * removes anything, so it runs again whenever it likes and picks up what Codex added to `home` since.
+ * Both folders have to exist; the person makes them, the way they sign in.
+ */
+export async function prepareShadowHome(home: string, shadow: string): Promise<ShadowHomeReport> {
+    const shared = resolve(home);
+    const own = resolve(shadow);
+    if (shared === own) {
+        throw new ShadowHomeError('The shadow home has to be another folder than the config folder');
+    }
+    for (const folder of SHARED_FOLDERS) {
+        await mkdir(join(shared, folder), { recursive: true });
+    }
+    const report: ShadowHomeReport = { linked: [], unshared: [], sharedLogin: false };
+    for (const name of PRIVATE_ENTRIES) {
+        if ((await existing(join(own, name))).kind === 'link') {
+            report.sharedLogin = true;
+        }
+    }
+    const names = (await readdir(shared)).filter((name) => !PRIVATE_ENTRIES.has(name) && !LOCAL_ENTRIES.has(name) && !isJournal(name));
+    for (const name of names.sort()) {
+        const target = join(shared, name);
+        const link = join(own, name);
+        const found = await existing(link);
+        if (found.kind === 'missing') {
+            await symlink(target, link);
+            report.linked.push(name);
+        } else if (found.kind === 'real' || resolve(own, found.target) !== target) {
+            report.unshared.push(name);
+        }
+    }
+    return report;
+}

package/src/providers/accounts/status.ts

@@ -0,0 +1,106 @@
+import type { AgentKind } from '@adecore/agent-contracts';
+import { withTimeout } from '../../async.ts';
+import { CodexTransport, type CodexClientInfo } from '../../chat/codex-transport.ts';
+import { runProcess } from '../../run-process.ts';
+
+/* A CLI that has not said who is signed in by now is not going to; the next pass asks again. */
+const ASK_TIMEOUT_MS = 20_000;
+
+/* Who a CLI says is signed in, from the CLI itself; the host never opens a credential. */
+export interface AccountReading {
+    signedIn: boolean;
+    email: string | null;
+    plan: string | null;
+    organization: string | null;
+}
+
+export type AskAccount = (kind: AgentKind, command: readonly string[], env: Record<string, string | undefined>) => Promise<AccountReading>;
+
+function text(value: unknown): string | null {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/* `claude auth status --json`, as Claude Code 2.1.282 prints it: `loggedIn`, `email`, `orgName`, `subscriptionType`. */
+export function readClaudeAuthStatus(output: string): AccountReading {
+    let status: unknown;
+    try {
+        status = JSON.parse(output);
+    } catch {
+        throw new Error('Claude Code did not say who is signed in');
+    }
+    if (!isRecord(status) || typeof status.loggedIn !== 'boolean') {
+        throw new Error('Claude Code did not say who is signed in');
+    }
+    return {
+        signedIn: status.loggedIn,
+        email: text(status.email),
+        plan: text(status.subscriptionType),
+        organization: text(status.orgName)
+    };
+}
+
+/*
+ * The app-server's `account/read`, as Codex 0.157 answers it: `account` is null while nobody signed in,
+ * `{ type: 'chatgpt', email, planType }` for a plan and `{ type: 'apiKey' }` for a key. A model
+ * provider without OpenAI's login needs no account at all, which `requiresOpenaiAuth` says.
+ */
+export function readCodexAccount(answer: unknown): AccountReading {
+    if (!isRecord(answer)) {
+        throw new Error('Codex did not say who is signed in');
+    }
+    const account = answer.account;
+    if (!isRecord(account)) {
+        return { signedIn: answer.requiresOpenaiAuth === false, email: null, plan: null, organization: null };
+    }
+    return { signedIn: true, email: text(account.email), plan: text(account.planType), organization: null };
+}
+
+async function askClaude(command: readonly string[], env: Record<string, string | undefined>): Promise<AccountReading> {
+    const { stdout } = await runProcess([...command, 'auth', 'status', '--json'], {
+        env,
+        timeoutMs: ASK_TIMEOUT_MS,
+        timeoutMessage: 'Claude Code did not answer in time'
+    });
+    // Signed out exits 1 and still prints the status, so the output decides and the exit code does not.
+    return readClaudeAuthStatus(stdout);
+}
+
+async function askCodex(command: readonly string[], env: Record<string, string | undefined>, client: CodexClientInfo): Promise<AccountReading> {
+    const transport = new CodexTransport({
+        command: [...command],
+        cwd: process.cwd(),
+        env: env as Record<string, string>,
+        onFrame: () => undefined,
+        onExit: () => undefined
+    });
+    try {
+        await withTimeout(
+            transport.request('initialize', { clientInfo: client, capabilities: { experimentalApi: true } }),
+            ASK_TIMEOUT_MS,
+            'Codex did not answer in time'
+        );
+        transport.notify('initialized', {});
+        const answer = await withTimeout(transport.request('account/read', { refreshToken: false }), ASK_TIMEOUT_MS, 'Codex did not answer in time');
+        return readCodexAccount(answer);
+    } finally {
+        transport.end();
+        transport.kill();
+    }
+}
+
+/* Starts the CLI in the account's environment and asks it; only Claude Code and Codex can say. */
+export function askAccountAs(client: CodexClientInfo): AskAccount {
+    return (kind, command, env) => {
+        if (kind === 'claude') {
+            return askClaude(command, env);
+        }
+        if (kind === 'codex') {
+            return askCodex(command, env, client);
+        }
+        return Promise.reject(new Error(`${kind} cannot say who is signed in`));
+    };
+}

package/src/providers/accounts/store.ts

@@ -0,0 +1,158 @@
+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 { CodedError } from '../../coded-error.ts';
+import { isNotFound, writeAtomic } from '../../fs.ts';
+import type { ChatProvider } from '../provider.ts';
+import {
+    accountFolder,
+    accountProblem,
+    defaultFolder,
+    expandHome,
+    folderVariablesOf,
+    isDefaultAccount,
+    isKnownKind,
+    readAccount,
+    withDefaults,
+    type Env
+} from './accounts.ts';
+import { DEFAULT_ACCOUNTS_HOST, redactVariables, type AccountsHost } from './variables.ts';
+
+const FILE_VERSION = 1;
+
+export function accountsPath(home: string): string {
+    return join(home, 'providers.json');
+}
+
+/*
+ * The accounts as the file holds them. A known kind is a parsed account; an unknown one is the entry
+ * exactly as it was read, so a newer version's fields survive this one writing the file.
+ */
+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> {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(await readFile(path, 'utf8'));
+    } catch (e) {
+        if (isNotFound(e) || e instanceof SyntaxError) {
+            return {};
+        }
+        throw e;
+    }
+    const entries = typeof parsed === 'object' && parsed !== null ? (parsed as { accounts?: unknown }).accounts : null;
+    if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+        return {};
+    }
+    const stored: StoredAccounts = {};
+    for (const [id, raw] of Object.entries(entries)) {
+        if (!ProviderAccountIdSchema.safeParse(id).success) {
+            continue;
+        }
+        const account = readAccount(id, raw, providerOf, env, host);
+        if (account !== null) {
+            stored[id] = account;
+        }
+    }
+    return stored;
+}
+
+export async function writeAccounts(path: string, stored: StoredAccounts): Promise<void> {
+    await writeAtomic(path, `${JSON.stringify({ version: FILE_VERSION, accounts: stored }, null, 2)}\n`, 0o600);
+}
+
+/* What a client reads of an entry of a kind it may not know either: the fields this version knows. */
+function wireAccount(entry: unknown): ProviderAccount {
+    const parsed = ProviderAccountSchema.safeParse(entry);
+    if (!parsed.success) {
+        return { kind: String((entry as { kind?: unknown }).kind) };
+    }
+    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 class InvalidAccountError extends CodedError<'invalid-account'> {
+    constructor(message: string) {
+        super('invalid-account', message);
+    }
+}
+
+function storedFolders(entry: unknown): Pick<ProviderAccount, 'home' | 'shadowHome'> {
+    const parsed = ProviderAccountSchema.safeParse(entry);
+    return parsed.success ? { home: parsed.data.home, shadowHome: parsed.data.shadowHome } : {};
+}
+
+/*
+ * What is wrong with the folders of an account a person points somewhere new, or null. An account
+ * whose folders did not change is left alone, so one whose folder went missing can still be renamed.
+ */
+function linkProblem(
+    id: string,
+    account: ProviderAccount,
+    before: unknown,
+    provider: ChatProvider,
+    env: Env,
+    isDirectory: (path: string) => boolean
+): string | null {
+    if (isDefaultAccount(id, account) || provider.home === undefined || account.home === undefined) {
+        return null;
+    }
+    const was = storedFolders(before);
+    if (was.home === account.home && was.shadowHome === account.shadowHome) {
+        return null;
+    }
+    for (const folder of [account.home, account.shadowHome]) {
+        if (folder !== undefined && !isDirectory(expandHome(folder, env))) {
+            return `${folder} is not a folder on this machine`;
+        }
+    }
+    if (accountFolder(id, account, provider, env) === defaultFolder(provider, env)) {
+        return `${defaultFolder(provider, env)} is the folder of the default ${provider.name} account`;
+    }
+    return null;
+}
+
+/*
+ * The whole map a person saved, as the file will hold it. A mistake in an account of a known kind
+ * refuses the save; an account of an unknown kind keeps the entry the file had under its id, which a
+ * 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: ProviderAccountMap,
+    before: StoredAccounts,
+    providerOf: (kind: AgentKind) => ChatProvider,
+    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)) {
+                throw new InvalidAccountError(`"${id}" is the id of the default ${id} account`);
+            }
+            const kept = before[id];
+            const keptKind = typeof kept === 'object' && kept !== null ? (kept as { kind?: unknown }).kind : undefined;
+            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);
+        if (problem !== null) {
+            throw new InvalidAccountError(`${id}: ${problem}`);
+        }
+        stored[id] = account;
+    }
+    return stored;
+}

package/src/providers/accounts/test-accounts.ts

@@ -0,0 +1,48 @@
+import type { AgentKind, ProviderAccountMap, ProviderInfo } from '@adecore/agent-contracts';
+import { providerFor } from '../registry.ts';
+import { ProviderAccountsService } from './service.ts';
+import { accountsPath, writeAccounts } from './store.ts';
+import type { SecretStore } from './variables.ts';
+
+/* A keychain in memory; `values` is what it holds, by key. */
+export function memorySecrets(values = new Map<string, string>()): SecretStore & { values: Map<string, string> } {
+    return {
+        values,
+        read: async (key) => values.get(key) ?? null,
+        write: async (key, value) => {
+            values.set(key, value);
+        },
+        remove: async (key) => {
+            values.delete(key);
+        }
+    };
+}
+
+/*
+ * The accounts of a machine as a test wants them: written to `providers.json` under `home` as
+ * they are, with only the folders in `folders` on disk, and every CLI signed in without being asked.
+ */
+export async function testAccounts(options: {
+    home: string;
+    env: Record<string, string | undefined>;
+    accounts: ProviderAccountMap;
+    // The folders that exist; a test takes one away to see what a missing folder does.
+    folders: Set<string>;
+}): Promise<ProviderAccountsService> {
+    const service = new ProviderAccountsService({
+        home: options.home,
+        providers: {
+            list: async () => (['claude', 'codex'] as AgentKind[]).map((kind) => ({ kind, installed: true }) as ProviderInfo),
+            get: (kind) => providerFor(kind)
+        },
+        env: options.env,
+        ask: async () => ({ signedIn: true, email: null, plan: null, organization: null }),
+        folderExists: (path) => options.folders.has(path),
+        prepareShadow: async () => ({ linked: [], unshared: [], sharedLogin: false }),
+        secrets: memorySecrets()
+    });
+    // Written and not saved, so an account whose folder is already gone is there the way a person left it.
+    await writeAccounts(accountsPath(options.home), options.accounts);
+    await service.load();
+    return service;
+}

package/src/providers/accounts/variables.ts

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import type { ProviderAccountVariable } from '@adecore/agent-contracts';
+import { CodedError } from '../../coded-error.ts';
+import { runProcess } from '../../run-process.ts';
+
+/*
+ * The variables of an account, and where a sensitive value is kept: the keychain of this machine,
+ * never `providers.json` and never the wire.
+ */
+
+export class SecretsUnavailableError extends CodedError<'secrets-unavailable'> {
+    constructor() {
+        super('secrets-unavailable', 'This machine has no keychain to keep a sensitive value in.');
+    }
+}
+
+/* What keeps the sensitive values; a test keeps them in memory. */
+export interface SecretStore {
+    /* Null for a key it has nothing under. */
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    /* Removing a key it has nothing under is not an error. */
+    remove(key: string): Promise<void>;
+}
+
+export function secretKey(accountId: string, name: string): string {
+    return `${accountId}/${name}`;
+}
+
+/* The names that decide which folder and which executable a CLI talks to. */
+const RESERVED = new Set(['HOME', 'PATH']);
+
+/* The app that runs the CLIs, as far as their accounts go: what a person calls it and which variables it sets itself. */
+export interface AccountsHost {
+    name: string;
+    // No account may set a variable with one of these prefixes, since the app sets them for every CLI.
+    variablePrefixes: readonly string[];
+    // Keeps the app's keychain values apart from any other app's.
+    keychainPrefix: string;
+}
+
+export const DEFAULT_ACCOUNTS_HOST: AccountsHost = { name: 'the app', variablePrefixes: [], keychainPrefix: 'agents' };
+
+/* The variables no account may set: the host's own and the ones that point a CLI at its folder. */
+export interface ReservedVariables {
+    host: AccountsHost;
+    folderVariables: readonly string[];
+}
+
+export function isReservedName(name: string, reserved: ReservedVariables): boolean {
+    return RESERVED.has(name) || reserved.host.variablePrefixes.some((prefix) => name.startsWith(prefix)) || reserved.folderVariables.includes(name);
+}
+
+/* `security` prints anything else as hex, so a read could not tell such a value from its own encoding. */
+function isPrintableAscii(value: string): boolean {
+    return /^[\x20-\x7e]*$/.test(value);
+}
+
+/* What is wrong with the variables of an account, or null when nothing is. A secret that is only redacted is judged by the service. */
+export function variablesProblem(variables: readonly ProviderAccountVariable[], reserved: ReservedVariables): string | null {
+    const seen = new Set<string>();
+    for (const variable of variables) {
+        if (seen.has(variable.name)) {
+            return `${variable.name} is set twice`;
+        }
+        seen.add(variable.name);
+        if (isReservedName(variable.name, reserved)) {
+            return `${variable.name} is set by ${reserved.host.name} itself`;
+        }
+        if (variable.sensitive && !isPrintableAscii(variable.value)) {
+            return `The value of ${variable.name} can only hold printable ASCII characters`;
+        }
+    }
+    return null;
+}
+
+/* The variables as a client may read them: a sensitive value never leaves the machine. */
+export function redactVariables(variables: readonly ProviderAccountVariable[]): ProviderAccountVariable[] {
+    return variables.map((variable) => (variable.sensitive ? { name: variable.name, value: '', sensitive: true, valueRedacted: true } : variable));
+}
+
+/* A data folder of its own (a development one beside an installed one) keeps its values apart from the other's. */
+export function keychainService(host: AccountsHost, home: string): string {
+    return `${host.keychainPrefix}-provider-env-${createHash('sha256').update(resolve(home)).digest('hex').slice(0, 12)}`;
+}
+// `security` exits with this when no item matches.
+const NOT_FOUND = 44;
+
+async function run(args: string[], stdin?: string): Promise<{ code: number; stdout: string; stderr: string }> {
+    const { exitCode, stdout, stderr } = await runProcess(['security', ...args], { ...(stdin === undefined ? {} : { stdin }) });
+    return { code: exitCode ?? 1, stdout, stderr };
+}
+
+/*
+ * Generic passwords in the login keychain, through the `security` CLI. A value goes in over stdin as
+ * hex in its interactive mode: on the command line any process could read it, and the password
+ * prompt cuts it at 128 characters.
+ */
+export function keychainSecrets(service: string): SecretStore {
+    return {
+        read: async (key) => {
+            const { code, stdout, stderr } = await run(['find-generic-password', '-s', service, '-a', key, '-w']);
+            if (code === NOT_FOUND) {
+                return null;
+            }
+            if (code !== 0) {
+                throw new Error(`The keychain did not give ${key}: ${stderr.trim()}`);
+            }
+            return stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout;
+        },
+        write: async (key, value) => {
+            const hex = Buffer.from(value, 'utf8').toString('hex');
+            const quoted = `"${key.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+            const { code, stderr } = await run(['-i'], `add-generic-password -U -s ${service} -a ${quoted} -X ${hex}\n`);
+            if (code !== 0) {
+                throw new Error(`The keychain did not take ${key}: ${stderr.trim()}`);
+            }
+        },
+        remove: async (key) => {
+            const { code, stderr } = await run(['delete-generic-password', '-s', service, '-a', key]);
+            if (code !== 0 && code !== NOT_FOUND) {
+                throw new Error(`The keychain did not remove ${key}: ${stderr.trim()}`);
+            }
+        }
+    };
+}
+
+/* The keychain on macOS; elsewhere none, so a sensitive variable is refused. */
+export function platformSecrets(host: AccountsHost, home: string): SecretStore | null {
+    return process.platform === 'darwin' ? keychainSecrets(keychainService(host, home)) : null;
+}

package/src/providers/catalog.ts

@@ -0,0 +1,90 @@
+import type { ModelCatalogData, ModelCatalogProfile, ModelInfo, ModelSelection } from '@adecore/agent-contracts';
+import manifest from './claude-models.json' with { type: 'json' };
+
+// What a host builds a catalog from; one that is never replaced needs no date.
+export type ModelCatalogInput = Omit<ModelCatalogData, 'updatedAt'> & { updatedAt?: string };
+
+function timeOf(data: ModelCatalogInput): number {
+    return data.updatedAt === undefined ? 0 : Date.parse(data.updatedAt);
+}
+
+/*
+ * The models a provider offers and what each one can be asked for. Bundled as JSON so a new
+ * model is a data change; a profile is only needed for a new combination of options. A host may
+ * swap in a newer copy while it runs, never one older than the copy it was built with.
+ */
+export class ModelCatalog {
+    private readonly shippedAt: number;
+    private data: ModelCatalogInput;
+
+    constructor(data: ModelCatalogInput = manifest as never) {
+        this.shippedAt = timeOf(data);
+        this.data = data;
+    }
+
+    get defaultModel(): string {
+        return this.data.defaultModel;
+    }
+
+    /* Takes a validated copy unless it is older than the shipped one; answers whether the models changed. */
+    replace(data: ModelCatalogData): boolean {
+        if (timeOf(data) < this.shippedAt) {
+            return false;
+        }
+        const changed = JSON.stringify(data) !== JSON.stringify(this.data);
+        this.data = data;
+        return changed;
+    }
+
+    list(): ModelInfo[] {
+        return this.data.models.map((model) => ({
+            slug: model.slug,
+            name: model.name,
+            badge: model.badge,
+            legacy: model.legacy === true,
+            isDefault: model.slug === this.data.defaultModel,
+            options: this.profileOf(model.slug)?.options ?? []
+        }));
+    }
+
+    /* What a person reads for a model, so an error in a thread names it the way the picker does. */
+    nameOf(slug: string): string {
+        return this.data.models.find((entry) => entry.slug === slug)?.name ?? slug;
+    }
+
+    /* Accepts a slug or an alias; unknown models answer null so the caller can decide what to do. */
+    resolveModel(name: string): string | null {
+        const model = this.data.models.find((entry) => entry.slug === name || entry.aliases?.includes(name));
+        return model?.slug ?? null;
+    }
+
+    /* Fills in defaults and drops options the model does not have, so a selection is always complete. */
+    normalize(selection: Partial<ModelSelection> | undefined): ModelSelection {
+        const model = (selection?.model && this.resolveModel(selection.model)) || this.defaultModel;
+        const options: ModelSelection['options'] = {};
+        for (const descriptor of this.profileOf(model)?.options ?? []) {
+            const given = selection?.options?.[descriptor.id];
+            if (descriptor.type === 'select') {
+                options[descriptor.id] =
+                    typeof given === 'string' && descriptor.choices.some((choice) => choice.id === given) ? given : descriptor.defaultChoice;
+            } else {
+                options[descriptor.id] = typeof given === 'boolean' ? given : descriptor.defaultValue;
+            }
+        }
+        return { model, options };
+    }
+
+    contextWindowFor(selection: ModelSelection): number | null {
+        const profile = this.profileOf(selection.model);
+        if (!profile) {
+            return null;
+        }
+        const chosen = selection.options.contextWindow;
+        return (typeof chosen === 'string' ? profile.contextWindowTokens[chosen] : undefined) ?? profile.contextWindowTokens['*'] ?? null;
+    }
+
+    private profileOf(slug: string): ModelCatalogProfile | undefined {
+        const model = this.data.models.find((entry) => entry.slug === slug);
+        return model ? this.data.profiles[model.profile] : undefined;
+    }
+}