@adecore/agents 0.31.1 → 0.31.3

package/src/chat/acp-protocol.ts

@@ -58,6 +58,48 @@ const SessionNotificationSchema = z.looseObject({ sessionId: z.string(), update:
 
 const PromptResponseSchema = z.looseObject({ stopReason: z.string() });
 
+const tokenCount = z.number().int().nonnegative();
+
+// Unstable in the protocol (`PromptResponse.usage`); only the three totals are required.
+const PromptUsageSchema = z.looseObject({
+    totalTokens: tokenCount,
+    inputTokens: tokenCount,
+    outputTokens: tokenCount,
+    thoughtTokens: tokenCount.nullish(),
+    cachedReadTokens: tokenCount.nullish(),
+    cachedWriteTokens: tokenCount.nullish()
+});
+
+/* The tokens of one turn with their kinds apart, as a usage record keeps them: `reasoning` is a part of `output`. */
+export interface AcpTurnUsage {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+
+/*
+ * The `usage` a `session/prompt` response carries, or null where the agent reports none. The protocol
+ * leaves open whether the input holds the cached part, so the total decides: when the kinds add up
+ * to more than it, the input counted the cache too and loses it here.
+ */
+export function promptUsageOf(result: unknown): AcpTurnUsage | null {
+    const response = z.looseObject({ usage: PromptUsageSchema }).safeParse(result);
+    if (!response.success) {
+        return null;
+    }
+    const usage = response.data.usage;
+    const cacheRead = usage.cachedReadTokens ?? 0;
+    const cacheWrite = usage.cachedWriteTokens ?? 0;
+    const apart = usage.inputTokens + usage.outputTokens + cacheRead + cacheWrite <= usage.totalTokens;
+    const input = apart ? usage.inputTokens : Math.max(0, usage.inputTokens - cacheRead - cacheWrite);
+    if (input + cacheRead + cacheWrite + usage.outputTokens === 0) {
+        return null;
+    }
+    return { input, cacheRead, cacheWrite, output: usage.outputTokens, reasoning: usage.thoughtTokens ?? 0 };
+}
+
 const ModeStateSchema = z.looseObject({
     currentModeId: z.string(),
     availableModes: z.array(z.unknown())
@@ -95,7 +137,8 @@ const InitializeResponseSchema = z.looseObject({
             sessionCapabilities: z
                 .looseObject({
                     resume: z.unknown().optional(),
-                    additionalDirectories: z.unknown().optional()
+                    additionalDirectories: z.unknown().optional(),
+                    close: z.unknown().optional()
                 })
                 .optional()
         })
@@ -126,6 +169,8 @@ export interface AcpAgentCapabilities {
     loadSession: boolean;
     resumeSession: boolean;
     additionalDirectories: boolean;
+    // Whether the agent takes `session/close`, which ends a session it would otherwise keep.
+    closeSession: boolean;
     images: boolean;
     authMethods: string[];
     agent: AcpAgentInfo | null;
@@ -144,6 +189,7 @@ export function parseInitialize(result: unknown): AcpAgentCapabilities {
         loadSession: capabilities?.loadSession === true,
         resumeSession: sessions?.resume !== undefined && sessions.resume !== null,
         additionalDirectories: sessions?.additionalDirectories !== undefined && sessions.additionalDirectories !== null,
+        closeSession: sessions?.close !== undefined && sessions.close !== null,
         images: capabilities?.promptCapabilities?.image === true,
         authMethods: validItems(AuthMethodSchema, parsed.data.authMethods).map((method) => method.id),
         agent: agent ? { name: agent.name, title: agent.title ?? null, version: agent.version } : null
@@ -436,11 +482,22 @@ function toolOutput(tool: ToolState): string | null {
     return null;
 }
 
+/* What an agent asks permission for, in the plain form a host's `autoAllow` judges it by. */
+export interface AcpPermissionRequest {
+    // The ACP tool kind (`execute`, `edit`, `fetch`, ...), or null when the agent names none.
+    kind: string | null;
+    title: string | null;
+    // Every text the call carries that may be what it runs: the command in its raw input and each text in its
+    // content. The agent decides which one it runs, so a host allows the call only when every one passes.
+    commands: string[];
+}
+
 /* A permission request as the backend acts on it: the event it raises, and the tool kind a runtime mode may answer it by. */
 export interface AcpPermission {
     requestId: string;
     rpcId: number | string;
     kind: string | null;
+    request: AcpPermissionRequest;
     events: BackendEvent[];
 }
 
@@ -558,7 +615,9 @@ export class AcpProtocol {
             description: tool.title === '' ? null : tool.title,
             canAllowAlways: options.some((option) => option.kind === 'allow_always')
         });
-        return { requestId, rpcId, kind: tool.kind, events };
+        const command = rawField(tool.rawInput, 'command', 'cmd');
+        const asked = { kind: tool.kind, title: tool.title === '' ? null : tool.title, commands: [...(command === null ? [] : [command]), ...tool.text] };
+        return { requestId, rpcId, kind: tool.kind, request: asked, events };
     }
 
     /*

package/src/chat/index.ts

@@ -1,6 +1,16 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
-export { type AcpAgentSpec, type AcpClientInfo, createAcpBackend } from './acp-backend.ts';
-export type { AcpAgentInfo, AcpModel, AcpModelState, AcpMode, AcpModeState, AcpSessionInfo, AcpModeMap } from './acp-protocol.ts';
+export { type AcpAgentSpec, type AcpClientInfo, type AcpUsageReport, createAcpBackend } from './acp-backend.ts';
+export type {
+    AcpAgentInfo,
+    AcpModel,
+    AcpModelState,
+    AcpMode,
+    AcpModeState,
+    AcpPermissionRequest,
+    AcpSessionInfo,
+    AcpModeMap,
+    AcpTurnUsage
+} from './acp-protocol.ts';
 export { AttachmentStore } from './attachment-store.ts';
 export type { BackendLaunch, TurnInput, ApprovalDecision, BackendEvent, BackendHost, ChatBackend } from './backend.ts';
 export { runningInBackground, type BackgroundWork } from './background-work.ts';

package/src/providers/accounts/acp-account.ts

@@ -0,0 +1,129 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_ACP_CLIENT, type AcpClientInfo } from '../../chat/acp-backend.ts';
+import { ACP_AUTH_REQUIRED, ACP_PROTOCOL_VERSION, parseInitialize, parseSessionInfo, sessionIdOf, type AcpSessionInfo } from '../../chat/acp-protocol.ts';
+import type { SpawnChatProcess } from '../../chat/chat-process.ts';
+import { JsonRpcError, JsonRpcTransport, type JsonRpcFrame } from '../../chat/json-rpc-transport.ts';
+import { ASK_TIMEOUT_MS, type AccountReading } from './status.ts';
+
+/* The clock the probe's deadline runs on; a test hands in one it moves itself. */
+export interface ProbeTimer {
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+export interface AcpAccountProbe {
+    // The agent as a person reads it, in the error a failed read carries.
+    name: string;
+    command: readonly string[];
+    env: Record<string, string | undefined>;
+    client?: AcpClientInfo;
+    spawn?: SpawnChatProcess;
+    timeoutMs?: number;
+    timer?: ProbeTimer;
+    // What the probe's session offered, for a host that fills its model catalog from the agent.
+    onSession?(info: AcpSessionInfo): void;
+}
+
+const SIGNED_OUT: AccountReading = { signedIn: false, email: null, plan: null, organization: null };
+const SIGNED_IN: AccountReading = { signedIn: true, email: null, plan: null, organization: null };
+
+const REAL_TIMER: ProbeTimer = {
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)
+};
+
+function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
+    return Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined));
+}
+
+function withDeadline<T>(work: Promise<T>, ms: number, timer: ProbeTimer, message: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const handle = timer.setTimeout(() => reject(new Error(message)), ms);
+        work.then(
+            (value) => {
+                timer.clearTimeout(handle);
+                resolve(value);
+            },
+            (e: unknown) => {
+                timer.clearTimeout(handle);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        );
+    });
+}
+
+/*
+ * Asks an ACP agent whether the account's environment is signed in: a session it opens means yes, "authentication
+ * required" means no. ACP has no request that says who, so a reading carries no email or plan. The session is opened
+ * in an empty folder of its own with no MCP servers, and `authenticate` is never sent: a probe must not start a login.
+ */
+export async function askAcpAccount(probe: AcpAccountProbe): Promise<AccountReading> {
+    const folder = await mkdtemp(join(tmpdir(), 'acp-account-'));
+    const client = probe.client ?? DEFAULT_ACP_CLIENT;
+    let transport: JsonRpcTransport | null = null;
+    try {
+        const started = new JsonRpcTransport({
+            command: [...probe.command],
+            cwd: folder,
+            env: definedEnv(probe.env),
+            ...(probe.spawn ? { spawn: probe.spawn } : {}),
+            label: probe.name,
+            errorName: 'AcpRpcError',
+            // The probe's own deadline covers every request.
+            requestTimeoutMs: null,
+            versionField: true,
+            onFrame: (frame) => refuseRequest(started, frame),
+            onExit: () => undefined
+        });
+        transport = started;
+        const reading = async (): Promise<AccountReading> => {
+            const capabilities = parseInitialize(
+                await started.request('initialize', {
+                    protocolVersion: ACP_PROTOCOL_VERSION,
+                    clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+                    clientInfo: { name: client.name, title: client.title ?? client.name, version: client.version }
+                })
+            );
+            if (capabilities.protocolVersion !== ACP_PROTOCOL_VERSION) {
+                throw new Error(`${probe.name} speaks ACP version ${capabilities.protocolVersion}; only version ${ACP_PROTOCOL_VERSION} is supported`);
+            }
+            let result: unknown;
+            try {
+                result = await started.request('session/new', { cwd: folder, mcpServers: [] });
+            } catch (error) {
+                if (error instanceof JsonRpcError && error.code === ACP_AUTH_REQUIRED) {
+                    return SIGNED_OUT;
+                }
+                throw error;
+            }
+            const sessionId = sessionIdOf(result);
+            if (sessionId === null) {
+                throw new Error(`${probe.name} opened a session without an id`);
+            }
+            probe.onSession?.(parseSessionInfo(result, sessionId, capabilities.agent));
+            if (capabilities.closeSession) {
+                // The answer is known by now; an agent that cannot close it keeps an empty session, nothing worse.
+                await started.request('session/close', { sessionId }).catch(() => undefined);
+            }
+            return SIGNED_IN;
+        };
+        return await withDeadline(reading(), probe.timeoutMs ?? ASK_TIMEOUT_MS, probe.timer ?? REAL_TIMER, `${probe.name} did not answer in time`);
+    } finally {
+        await transport?.dispose();
+        await rm(folder, { recursive: true, force: true });
+    }
+}
+
+/* The probe advertises nothing, so a request from the agent gets a refusal rather than a silence it would wait on. */
+function refuseRequest(transport: JsonRpcTransport, frame: JsonRpcFrame): void {
+    if (frame.id === undefined || frame.id === null || !transport.alive) {
+        return;
+    }
+    try {
+        transport.respondError(frame.id as number | string, -32601, `Method not found: ${String(frame.method)}`);
+    } catch {
+        // The agent closed its input; the deadline or the exit settles the probe.
+    }
+}

package/src/providers/accounts/service.ts

@@ -32,7 +32,7 @@ import {
 } from './accounts.ts';
 import { AccountError, isDefaultAccountOf, type AccountLaunches } from './launch.ts';
 import { prepareShadowHome, type ShadowHomeReport } from './shadow-home.ts';
-import { askAccountAs, type AskAccount } from './status.ts';
+import { ASKED_KINDS, askAccountAs, type AskAccount } from './status.ts';
 import { acceptAccounts, accountsPath, InvalidAccountError, readAccounts, wireAccounts, writeAccounts, type StoredAccounts } from './store.ts';
 import { DEFAULT_ACCOUNTS_HOST, platformSecrets, secretKey, SecretsUnavailableError, type AccountsHost, type SecretStore } from './variables.ts';
 
@@ -52,7 +52,7 @@ export interface ProviderAccountsOptions {
     // `kinds` are the CLIs that get a default account; absent, every kind this version knows.
     providers: { list(): Promise<ProviderInfo[]>; get(kind: AgentKind): ChatProvider; enabled?(kind: AgentKind): boolean; kinds?(): readonly AgentKind[] };
     env?: Env;
-    // How to ask a CLI who is signed in; a test answers without starting one.
+    // How to ask a CLI who is signed in, for every kind whose provider has no reader of its own; a test answers without starting one.
     ask?: AskAccount;
     prepareShadow?: (home: string, shadow: string) => Promise<ShadowHomeReport>;
     folderExists?: (path: string) => boolean;
@@ -127,6 +127,8 @@ export class ProviderAccountsService implements AccountLaunches {
     private readonly providers: ProviderAccountsOptions['providers'];
     private readonly env: Env;
     private readonly ask: AskAccount;
+    // A host's own `ask` is taken to answer for every kind; the default only for `ASKED_KINDS`.
+    private readonly asksEveryKind: boolean;
     private readonly prepareShadow: NonNullable<ProviderAccountsOptions['prepareShadow']>;
     private readonly folderExists: NonNullable<ProviderAccountsOptions['folderExists']>;
     private readonly install: ProviderAccountsOptions['install'];
@@ -154,6 +156,7 @@ export class ProviderAccountsService implements AccountLaunches {
         this.providers = options.providers;
         this.env = options.env ?? process.env;
         this.ask = options.ask ?? askAccountAs(options.client ?? DEFAULT_CODEX_CLIENT);
+        this.asksEveryKind = options.ask !== undefined;
         this.prepareShadow = options.prepareShadow ?? prepareShadowHome;
         this.folderExists = options.folderExists ?? isFolder;
         this.install = options.install;
@@ -176,10 +179,15 @@ export class ProviderAccountsService implements AccountLaunches {
     snapshot(): ProviderAccounts {
         const loginCommands: Partial<Record<AgentKind, string>> = {};
         const chatLogins: AgentKind[] = [];
+        const silentLogins: AgentKind[] = [];
         for (const kind of this.kinds()) {
-            const home = this.providers.get(kind).home;
+            const provider = this.providers.get(kind);
+            const home = provider.home;
             if (home?.loginCommand !== undefined) {
                 loginCommands[kind] = home.loginCommand;
+                if (provider.askAccount === undefined && !this.asksEveryKind && !ASKED_KINDS.includes(kind)) {
+                    silentLogins.push(kind);
+                }
             } else if (home !== undefined) {
                 chatLogins.push(kind);
             }
@@ -189,7 +197,8 @@ export class ProviderAccountsService implements AccountLaunches {
             statuses: Object.entries(this.accounts).map(([id, account]) => this.statusOf(id, account)),
             secretsAvailable: this.secrets !== null,
             loginCommands,
-            ...(chatLogins.length > 0 ? { chatLogins } : {})
+            ...(chatLogins.length > 0 ? { chatLogins } : {}),
+            ...(silentLogins.length > 0 ? { silentLogins } : {})
         };
     }
 
@@ -619,7 +628,8 @@ export class ProviderAccountsService implements AccountLaunches {
             if (provider.home.loginCommand === undefined) {
                 return this.status(id, account, 'ready', { message });
             }
-            const reading = await this.ask(kind, provider.command, accountEnv(id, account, provider, this.env, values));
+            const env = accountEnv(id, account, provider, this.env, values);
+            const reading = await (provider.askAccount ? provider.askAccount(provider.command, env) : this.ask(kind, provider.command, env));
             return this.status(id, account, reading.signedIn ? 'ready' : 'signed-out', {
                 email: reading.email,
                 plan: reading.plan,

package/src/providers/accounts/status.ts

@@ -5,7 +5,7 @@ import { CodexTransport, type CodexClientInfo } from '../../chat/codex-transport
 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;
+export 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 {
@@ -89,6 +89,9 @@ async function askCodex(command: readonly string[], env: Record<string, string |
     }
 }
 
+/* The kinds `askAccountAs` can ask; a provider with a reader of its own answers for itself. */
+export const ASKED_KINDS: readonly AgentKind[] = ['claude', 'codex'];
+
 /* 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) => {

package/src/providers/acp-provider.ts

@@ -1,5 +1,8 @@
 import type { AgentKind, ProviderCapabilities, ProviderInstall } from '@adecore/agent-contracts';
-import { createAcpBackend, type AcpAgentSpec } from '../chat/acp-backend.ts';
+import { createAcpBackend, type AcpAgentSpec, type AcpUsageReport } from '../chat/acp-backend.ts';
+import type { AcpSessionInfo } from '../chat/acp-protocol.ts';
+import { askAcpAccount } from './accounts/acp-account.ts';
+import { writeAcpUsage } from './acp-usage-log.ts';
 import type { ModelCatalog } from './catalog.ts';
 import { detectCli, type CliDetection } from './detect.ts';
 import type { ChatProvider, ProviderHome } from './provider.ts';
@@ -47,10 +50,38 @@ export interface AcpProviderSpec extends AcpAgentSpec {
     // Absent asks the executable for `--version`.
     detect?(command: string, env: Record<string, string | undefined>): Promise<CliDetection>;
     enabled?(): boolean;
+    // Absent or true asks the agent over ACP whether an account is signed in; false leaves that to the host.
+    accountProbe?: boolean;
+    // Absent or true lets the models a session reports replace the catalog's; false keeps the catalog as the host built it.
+    adoptModels?: boolean;
+    // The folder the usage of every turn the agent reports is logged to, for a usage root of the agent's kind; absent logs nothing.
+    usageLog?: string;
+}
+
+/* Agents whose own usage files the scanner reads; a log of their turns would count every one twice. */
+const OWN_USAGE_FILES: ReadonlySet<AgentKind> = new Set(['grok']);
+
+/* An agent's model id may reach a command line, so one that reads as a flag is left out. */
+function adoptableModels(info: AcpSessionInfo): Array<{ slug: string; name: string }> {
+    return (info.models?.models ?? []).filter((model) => model.id !== '' && !model.id.startsWith('-')).map((model) => ({ slug: model.id, name: model.name }));
 }
 
 export function createAcpProvider(spec: AcpProviderSpec): ChatProvider {
     const capabilities = { ...ACP_CAPABILITIES, ...spec.capabilities };
+    const onSession = (info: AcpSessionInfo): void => {
+        if (spec.adoptModels !== false && info.models !== null) {
+            spec.catalog.adopt(adoptableModels(info), info.models.current);
+        }
+        spec.onSession?.(info);
+    };
+    const usageLog = spec.usageLog === undefined || OWN_USAGE_FILES.has(spec.kind) ? null : spec.usageLog;
+    const onUsage =
+        usageLog === null
+            ? spec.onUsage
+            : (report: AcpUsageReport): void => {
+                  writeAcpUsage(usageLog, report, Date.now());
+                  spec.onUsage?.(report);
+              };
     return {
         kind: spec.kind,
         name: spec.name,
@@ -70,6 +101,18 @@ export function createAcpProvider(spec: AcpProviderSpec): ChatProvider {
                 throw new Error(`${spec.name} is only available as a chat.`);
             }),
         detect: spec.detect ?? ((command, env) => detectCli(command, env)),
-        createBackend: createAcpBackend(spec)
+        ...(spec.accountProbe === false
+            ? {}
+            : {
+                  askAccount: (command, env) =>
+                      askAcpAccount({
+                          name: spec.name,
+                          command,
+                          env: { ...env, ...spec.env },
+                          ...(spec.client ? { client: spec.client } : {}),
+                          onSession
+                      })
+              }),
+        createBackend: createAcpBackend({ ...spec, onSession, ...(onUsage === undefined ? {} : { onUsage }) })
     };
 }

package/src/providers/acp-usage-log.ts

@@ -0,0 +1,26 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AcpUsageReport } from '../chat/acp-backend.ts';
+import { errorText } from '../error-text.ts';
+import { hostUsageLine } from '../usage/readers/host-log.ts';
+
+/*
+ * Appends one turn to the session's own file in the folder, so a scan that hashes what it already read
+ * of a file never rereads the log of every other session. Written at once, since it is one line per turn.
+ */
+export function writeAcpUsage(folder: string, report: AcpUsageReport, at: number): void {
+    const { sessionId, cwd, model, ...tokens } = report;
+    try {
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        appendFileSync(
+            join(folder, `${encodeURIComponent(sessionId === '' ? 'session' : sessionId)}.jsonl`),
+            hostUsageLine({ at, model, session: sessionId, cwd, ...tokens }),
+            {
+                mode: 0o600
+            }
+        );
+    } catch (e) {
+        // A turn whose line could not be written is missing from the usage page; the chat itself goes on.
+        console.warn('Could not write the usage of an ACP turn:', errorText(e));
+    }
+}

package/src/providers/catalog.ts

@@ -4,6 +4,8 @@ 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 };
 
+const ADOPTED_PROFILE = 'agent';
+
 function timeOf(data: ModelCatalogInput): number {
     return data.updatedAt === undefined ? 0 : Date.parse(data.updatedAt);
 }
@@ -36,6 +38,27 @@ export class ModelCatalog {
         return changed;
     }
 
+    /*
+     * Takes the models an agent reported for itself in place of the list, the agent's current model as the
+     * default and its order kept; answers whether the models changed. Every model gets the profile the
+     * default has now, as an agent names its models but not what each can be asked for.
+     */
+    adopt(models: ReadonlyArray<{ slug: string; name: string }>, defaultModel: string): boolean {
+        if (models.length === 0 || !models.some((model) => model.slug === defaultModel)) {
+            return false;
+        }
+        const profile = this.profileOf(this.data.defaultModel) ?? { options: [], contextWindowTokens: {} };
+        const data: ModelCatalogInput = {
+            ...(this.data.updatedAt === undefined ? {} : { updatedAt: this.data.updatedAt }),
+            defaultModel,
+            profiles: { [ADOPTED_PROFILE]: profile },
+            models: models.map((model) => ({ slug: model.slug, name: model.name, profile: ADOPTED_PROFILE }))
+        };
+        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,

package/src/providers/index.ts

@@ -1,5 +1,6 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
 export { ACP_CAPABILITIES, type AcpProviderSpec, createAcpProvider } from './acp-provider.ts';
+export { type AcpAccountProbe, askAcpAccount, type ProbeTimer } from './accounts/acp-account.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';
@@ -12,5 +13,6 @@ export { type CodexRules, codexRulesText, codexRulesPathIn, defaultCodexHome, in
 export { codexThreadOptions, codexServiceTier } from './codex.ts';
 export { type CliDetection, detectCli } from './detect.ts';
 export type { ChatProvider, ProviderHome } from './provider.ts';
+export { isOnlyCommands } from './shell-commands.ts';
 export { ProviderRegistry, type ProviderRegistryOptions } from './registry.ts';
 export { MODE_ORDER, narrowerMode, ceilingForOpening, modeFlag } from '../modes.ts';

package/src/providers/provider.ts

@@ -1,5 +1,6 @@
 import type { AgentKind, ProviderCapabilities, ProviderInstall } from '@adecore/agent-contracts';
 import type { BackendHost, BackendLaunch, ChatBackend } from '../chat/backend.ts';
+import type { AccountReading } from './accounts/status.ts';
 import type { ModelCatalog } from './catalog.ts';
 import type { CliDetection } from './detect.ts';
 
@@ -47,5 +48,7 @@ export interface ChatProvider {
     detect(command: string, env: Record<string, string | undefined>): Promise<CliDetection>;
     // Whether a person turned this provider on, for one that is off until they do; absent is always on.
     enabled?(): boolean;
+    /* Asks the CLI, started in an account's environment, who is signed in there. Absent leaves the host's own reader. */
+    askAccount?(command: readonly string[], env: Record<string, string | undefined>): Promise<AccountReading>;
     createBackend(launch: BackendLaunch, host: BackendHost): ChatBackend;
 }

package/src/providers/shell-commands.ts

@@ -0,0 +1,122 @@
+// Unquoted, each of these makes the shell do more than run a word list: a pipe, a redirect, an expansion,
+// a subshell or group, a glob, a comment or a history or negation mark.
+const REFUSED = new Set(['|', '>', '<', '$', '`', '(', ')', '{', '}', '*', '?', '[', '~', '#', '!']);
+
+/*
+ * Whether a shell command line is only simple commands, joined by `&&`, `||`, `;` or newlines, each of
+ * which starts with one of `allowed`. Anything the tokenizer cannot prove simple answers false, so a
+ * true is safe to act on without a person: a pipe, a redirect, an expansion, a subshell, a background
+ * `&`, an unquoted glob or an unbalanced quote all refuse the whole line.
+ */
+export function isOnlyCommands(command: string, allowed: readonly string[]): boolean {
+    let word = '';
+    let inWord = false;
+    let words: string[] = [];
+    let commands = 0;
+    // A separator that still needs a command after it; a trailing `;` or newline needs none.
+    let dangling = false;
+
+    const endWord = (): void => {
+        if (inWord) {
+            words.push(word);
+        }
+        word = '';
+        inWord = false;
+    };
+
+    const endCommand = (separator: string): boolean => {
+        endWord();
+        if (words.length === 0) {
+            // Blank lines are fine, and so is a newline after `&&` or `||`; an empty command before any other separator is not.
+            return separator === '\n';
+        }
+        if (!allowed.includes(words[0]!)) {
+            return false;
+        }
+        commands++;
+        words = [];
+        dangling = separator === '&&' || separator === '||';
+        return true;
+    };
+
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i]!;
+        const next = command[i + 1];
+        if (char === ' ' || char === '\t') {
+            endWord();
+            continue;
+        }
+        if (char === '\n' || char === ';') {
+            if (!endCommand(char)) {
+                return false;
+            }
+            continue;
+        }
+        if ((char === '&' || char === '|') && next === char) {
+            if (!endCommand(char + next)) {
+                return false;
+            }
+            i++;
+            continue;
+        }
+        if (char === '&' || REFUSED.has(char)) {
+            return false;
+        }
+        if (char === '\\') {
+            if (next === undefined) {
+                return false;
+            }
+            i++;
+            if (next !== '\n') {
+                word += next;
+                inWord = true;
+            }
+            continue;
+        }
+        if (char === "'") {
+            const close = command.indexOf("'", i + 1);
+            if (close === -1) {
+                return false;
+            }
+            word += command.slice(i + 1, close);
+            inWord = true;
+            i = close;
+            continue;
+        }
+        if (char === '"') {
+            inWord = true;
+            let closed = false;
+            for (i++; i < command.length; i++) {
+                const quoted = command[i]!;
+                if (quoted === '"') {
+                    closed = true;
+                    break;
+                }
+                if (quoted === '$' || quoted === '`') {
+                    return false;
+                }
+                if (quoted === '\\') {
+                    const escaped = command[i + 1];
+                    if (escaped === undefined) {
+                        return false;
+                    }
+                    i++;
+                    if (escaped === '"' || escaped === '\\' || escaped === '$' || escaped === '`') {
+                        word += escaped;
+                    } else if (escaped !== '\n') {
+                        word += quoted + escaped;
+                    }
+                    continue;
+                }
+                word += quoted;
+            }
+            if (!closed) {
+                return false;
+            }
+            continue;
+        }
+        word += char;
+        inWord = true;
+    }
+    return endCommand('\n') && commands > 0 && !dangling;
+}