@adecore/agents 0.29.3 → 0.31.0

package/src/providers/acp-provider.ts

@@ -0,0 +1,73 @@
+import type { AgentKind, ProviderCapabilities } from '@adecore/agent-contracts';
+import { createAcpBackend, type AcpAgentSpec } from '../chat/acp-backend.ts';
+import type { ModelCatalog } from './catalog.ts';
+import { detectCli, type CliDetection } from './detect.ts';
+import type { ChatProvider, ProviderHome } from './provider.ts';
+
+/*
+ * What every ACP agent can do through this backend. A file change comes as the text before and after;
+ * a message names its mentions and attachments by path, as text the agent opens with its own tools.
+ */
+export const ACP_CAPABILITIES: ProviderCapabilities = {
+    chat: true,
+    terminal: false,
+    hooks: false,
+    streamsToolOutput: false,
+    diffs: 'before-after',
+    attachments: true,
+    mentions: true,
+    denyReason: false,
+    allowAlways: true,
+    asyncQuestions: false,
+    compaction: 'none',
+    reportsCost: false,
+    reportsContextWindow: false,
+    reportsThinking: true,
+    slashCommands: true
+};
+
+/* One ACP agent as a host offers it: the backend's spec, plus what makes it a provider. */
+export interface AcpProviderSpec extends AcpAgentSpec {
+    kind: AgentKind;
+    // The executable, and the arguments that start it as an ACP agent on its stdio.
+    command: string;
+    args?: readonly string[];
+    catalog: ModelCatalog;
+    // Over `ACP_CAPABILITIES`, for an agent that reports its cost or context window, or whose commands fold its context.
+    capabilities?: Partial<ProviderCapabilities>;
+    // What a terminal runs to continue one of its sessions; empty where it has none.
+    resumeCommand?: string;
+    home?: ProviderHome;
+    ignoresProjectConfig?: boolean;
+    oneShotArgs?(prompt: string): string[];
+    oneShotStdinArgs?: readonly string[];
+    // Absent leaves the agent to chats only.
+    firstPromptArgs?(prompt: string): string[];
+    // Absent asks the executable for `--version`.
+    detect?(command: string, env: Record<string, string | undefined>): Promise<CliDetection>;
+    enabled?(): boolean;
+}
+
+export function createAcpProvider(spec: AcpProviderSpec): ChatProvider {
+    const capabilities = { ...ACP_CAPABILITIES, ...spec.capabilities };
+    return {
+        kind: spec.kind,
+        name: spec.name,
+        catalog: spec.catalog,
+        capabilities,
+        command: [spec.command, ...(spec.args ?? [])],
+        resumeCommand: spec.resumeCommand ?? '',
+        ...(spec.ignoresProjectConfig === undefined ? {} : { ignoresProjectConfig: spec.ignoresProjectConfig }),
+        ...(spec.home ? { home: spec.home } : {}),
+        ...(spec.oneShotArgs ? { oneShotArgs: spec.oneShotArgs } : {}),
+        ...(spec.oneShotStdinArgs ? { oneShotStdinArgs: spec.oneShotStdinArgs } : {}),
+        ...(spec.enabled ? { enabled: spec.enabled } : {}),
+        firstPromptArgs:
+            spec.firstPromptArgs ??
+            (() => {
+                throw new Error(`${spec.name} is only available as a chat.`);
+            }),
+        detect: spec.detect ?? ((command, env) => detectCli(command, env)),
+        createBackend: createAcpBackend(spec)
+    };
+}

package/src/providers/catalog.ts

@@ -41,6 +41,7 @@ export class ModelCatalog {
             slug: model.slug,
             name: model.name,
             badge: model.badge,
+            ...(model.vendor === undefined ? {} : { vendor: model.vendor }),
             legacy: model.legacy === true,
             isDefault: model.slug === this.data.defaultModel,
             options: this.profileOf(model.slug)?.options ?? [],

package/src/providers/index.ts

@@ -1,4 +1,5 @@
 // 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 { 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/src/providers/provider.ts

@@ -11,7 +11,8 @@ export interface ProviderHome {
     // Variables that sign the CLI in on their own, over whatever login the folder holds.
     readonly loginEnv: readonly string[];
     // What a person types in a terminal to sign in; the account's folder comes from the terminal's environment.
-    readonly loginCommand: string;
+    // Absent on a CLI that signs in from its first chat, which nothing outside that chat can ask about.
+    readonly loginCommand?: string;
 }
 
 /*

package/src/providers/registry.ts

@@ -94,6 +94,11 @@ export class ProviderRegistry {
         );
     }
 
+    /* The kinds this host offers, in the order every menu lists them. */
+    kinds(): AgentKind[] {
+        return this.providers.map((provider) => provider.kind);
+    }
+
     /* The provider of a kind, one this host does not offer included. */
     get(kind: AgentKind): ChatProvider {
         return this.providers.find((provider) => provider.kind === kind) ?? this.fallback(kind);

package/src/testing/fake-acp.ts

@@ -0,0 +1,296 @@
+/*
+ * Network-free ACP agent. Prompt commands exercise permissions, cancels, plans, edits and resumes
+ * through the JSON-RPC shapes of the Agent Client Protocol, version 1.
+ */
+import type { FakeCli } from './fake-cli.ts';
+
+type Frame = Record<string, unknown>;
+
+// The prompts of every session, outside any one process: a real agent keeps them on disk, so a later process loads them too.
+const sessionHistory = new Map<string, string[]>();
+
+export interface FakeAcpOptions {
+    // Advertises `loadSession`; on by default.
+    loadSession?: boolean;
+    // Advertises `session/resume`, which a client then prefers over a load.
+    resumeSession?: boolean;
+    // Answers session requests with "authentication required" until `authenticate` names this method.
+    authMethod?: string;
+    // The modes the session offers, as `session/set_mode` takes them; empty offers none.
+    modes?: readonly string[];
+    // Reports models the way agents did before config options: `models` and `session/set_model`.
+    legacyModels?: boolean;
+}
+
+export function fakeAcpWith(options: FakeAcpOptions): FakeCli {
+    return (io) => {
+        const modes = options.modes ?? ['ask', 'edit', 'yolo'];
+        let authenticated = options.authMethod === undefined;
+        let sessionId = '';
+        let mode = modes[0] ?? '';
+        let model = 'fake-small';
+        let serverRequestId = 0;
+        let callCounter = 0;
+        let prompt: { rpcId: number | string; cancelled: boolean } | null = null;
+        let permission: { rpcId: number; onAnswer(outcome: Frame): void } | null = null;
+
+        const send = (frame: Frame): void => {
+            io.out({ jsonrpc: '2.0', ...frame });
+        };
+
+        const respond = (id: unknown, result: unknown): void => {
+            send({ id, result });
+        };
+
+        const refuse = (id: unknown, code: number, message: string): void => {
+            send({ id, error: { code, message } });
+        };
+
+        const update = (fields: Frame): void => {
+            send({ method: 'session/update', params: { sessionId, update: fields } });
+        };
+
+        const say = (text: string): void => {
+            const half = Math.ceil(text.length / 2);
+            update({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: text.slice(0, half) } });
+            update({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: text.slice(half) } });
+        };
+
+        const endTurn = (stopReason: string): void => {
+            if (prompt === null) {
+                return;
+            }
+            update({ sessionUpdate: 'usage_update', used: 1200, size: 200000, cost: { amount: 0.01, currency: 'USD' } });
+            respond(prompt.rpcId, { stopReason });
+            prompt = null;
+        };
+
+        const sessionState = (): Frame => {
+            const modelChoices = [
+                { value: 'fake-small', name: 'Fake small' },
+                { value: 'fake-large', name: 'Fake large' }
+            ];
+            return {
+                ...(modes.length === 0 ? {} : { modes: { currentModeId: mode, availableModes: modes.map((id) => ({ id, name: id })) } }),
+                ...(options.legacyModels
+                    ? { models: { currentModelId: model, availableModels: modelChoices.map((choice) => ({ modelId: choice.value, name: choice.name })) } }
+                    : { configOptions: [{ id: 'model', name: 'Model', type: 'select', category: 'model', currentValue: model, options: modelChoices }] })
+            };
+        };
+
+        const askPermission = (toolCall: Frame, onAnswer: (outcome: Frame) => void): void => {
+            const rpcId = serverRequestId++;
+            permission = { rpcId, onAnswer };
+            send({
+                id: rpcId,
+                method: 'session/request_permission',
+                params: {
+                    sessionId,
+                    toolCall,
+                    options: [
+                        { optionId: 'once', name: 'Allow once', kind: 'allow_once' },
+                        { optionId: 'always', name: 'Always allow', kind: 'allow_always' },
+                        { optionId: 'no', name: 'Reject', kind: 'reject_once' }
+                    ]
+                }
+            });
+        };
+
+        const handlePrompt = (id: unknown, params: Frame): void => {
+            const blocks = Array.isArray(params.prompt) ? (params.prompt as Frame[]) : [];
+            const text = blocks
+                .filter((block) => block.type === 'text')
+                .map((block) => String(block.text))
+                .join('\n');
+            const images = blocks.filter((block) => block.type === 'image').length;
+            const history = sessionHistory.get(sessionId) ?? [];
+            sessionHistory.set(sessionId, [...history, text]);
+            prompt = { rpcId: id as number | string, cancelled: false };
+            const last = text.split('\n\n').at(-1) ?? text;
+            if (last === 'history?') {
+                say(`prompts before: ${history.length}`);
+                endTurn('end_turn');
+                return;
+            }
+            if (last === 'mode?') {
+                say(`mode: ${mode}, model: ${model}`);
+                endTurn('end_turn');
+                return;
+            }
+            if (last === 'crash') {
+                io.exit(1);
+                return;
+            }
+            if (last === 'slow') {
+                say('working');
+                return;
+            }
+            if (last === 'plan') {
+                update({
+                    sessionUpdate: 'plan',
+                    entries: [
+                        { content: 'Read the code', priority: 'high', status: 'completed' },
+                        { content: 'Write the fix', priority: 'medium', status: 'in_progress' }
+                    ]
+                });
+                endTurn('end_turn');
+                return;
+            }
+            if (last === 'refuse' || last === 'max tokens') {
+                say('no');
+                endTurn(last === 'refuse' ? 'refusal' : 'max_tokens');
+                return;
+            }
+            if (last.startsWith('edit:')) {
+                const path = last.slice(5).trim();
+                const toolCallId = `call-${++callCounter}`;
+                const content = [{ type: 'diff', path, oldText: 'one\ntwo\n', newText: 'one\nthree\n' }];
+                update({ sessionUpdate: 'tool_call', toolCallId, title: `Edit ${path}`, kind: 'edit', status: 'pending', locations: [{ path }] });
+                askPermission({ toolCallId, title: `Edit ${path}`, kind: 'edit', content }, (outcome) => {
+                    const allowed = outcome.outcome === 'selected' && outcome.optionId !== 'no';
+                    update({ sessionUpdate: 'tool_call_update', toolCallId, status: allowed ? 'completed' : 'failed', content });
+                    endTurn(outcome.outcome === 'cancelled' ? 'cancelled' : 'end_turn');
+                });
+                return;
+            }
+            if (last.startsWith('tool:')) {
+                const command = last.slice(5).trim();
+                const toolCallId = `call-${++callCounter}`;
+                update({ sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'I should run it.' } });
+                update({ sessionUpdate: 'tool_call', toolCallId, title: `Run ${command}`, kind: 'execute', status: 'pending', rawInput: { command } });
+                askPermission({ toolCallId }, (outcome) => {
+                    if (outcome.outcome === 'cancelled') {
+                        update({ sessionUpdate: 'tool_call_update', toolCallId, status: 'failed' });
+                        endTurn('cancelled');
+                        return;
+                    }
+                    if (outcome.optionId === 'no') {
+                        update({
+                            sessionUpdate: 'tool_call_update',
+                            toolCallId,
+                            status: 'failed',
+                            content: [{ type: 'content', content: { type: 'text', text: 'rejected' } }]
+                        });
+                        say('not run');
+                        endTurn('end_turn');
+                        return;
+                    }
+                    update({ sessionUpdate: 'tool_call_update', toolCallId, status: 'in_progress' });
+                    update({
+                        sessionUpdate: 'tool_call_update',
+                        toolCallId,
+                        status: 'completed',
+                        content: [{ type: 'content', content: { type: 'text', text: `ran ${command} (${String(outcome.optionId)})` } }]
+                    });
+                    say('done');
+                    endTurn('end_turn');
+                });
+                return;
+            }
+            update({ sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'Thinking.' } });
+            say(`echo: ${text}${images > 0 ? ` (${images} images)` : ''}`);
+            endTurn('end_turn');
+        };
+
+        const handle = (frame: Frame): void => {
+            const id = frame.id;
+            const params = (typeof frame.params === 'object' && frame.params !== null ? frame.params : {}) as Frame;
+            if (frame.method === undefined) {
+                // The client's answer to a permission request.
+                if (permission !== null && id === permission.rpcId) {
+                    const answered = permission;
+                    permission = null;
+                    const result = frame.result as { outcome?: Frame } | undefined;
+                    answered.onAnswer(result?.outcome ?? { outcome: 'cancelled' });
+                }
+                return;
+            }
+            switch (frame.method) {
+                case 'initialize':
+                    respond(id, {
+                        protocolVersion: 1,
+                        agentCapabilities: {
+                            loadSession: options.loadSession ?? true,
+                            promptCapabilities: { image: true, audio: false, embeddedContext: false },
+                            sessionCapabilities: options.resumeSession ? { resume: {} } : {}
+                        },
+                        authMethods: options.authMethod === undefined ? [] : [{ id: options.authMethod, name: 'Sign in' }],
+                        agentInfo: { name: 'fake-acp', title: 'Fake ACP', version: '0.0.1' }
+                    });
+                    return;
+                case 'authenticate':
+                    authenticated = params.methodId === options.authMethod;
+                    respond(id, {});
+                    return;
+                case 'session/new':
+                    if (!authenticated) {
+                        refuse(id, -32000, 'Authentication required');
+                        return;
+                    }
+                    sessionId = `fake-session-${Math.random().toString(36).slice(2, 8)}`;
+                    sessionHistory.set(sessionId, []);
+                    respond(id, { sessionId, ...sessionState() });
+                    return;
+                case 'session/load':
+                case 'session/resume': {
+                    const history = sessionHistory.get(String(params.sessionId));
+                    if (!authenticated) {
+                        refuse(id, -32000, 'Authentication required');
+                        return;
+                    }
+                    if (history === undefined) {
+                        refuse(id, -32002, 'Session not found');
+                        return;
+                    }
+                    sessionId = String(params.sessionId);
+                    if (frame.method === 'session/load') {
+                        for (const earlier of history) {
+                            update({ sessionUpdate: 'user_message_chunk', content: { type: 'text', text: earlier } });
+                            update({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'replayed' } });
+                        }
+                    }
+                    respond(id, sessionState());
+                    return;
+                }
+                case 'session/set_mode':
+                    mode = String(params.modeId);
+                    respond(id, {});
+                    update({ sessionUpdate: 'current_mode_update', currentModeId: mode });
+                    return;
+                case 'session/set_model':
+                    model = String(params.modelId);
+                    respond(id, {});
+                    return;
+                case 'session/set_config_option':
+                    if (params.configId === 'model') {
+                        model = String(params.value);
+                    }
+                    respond(id, { configOptions: sessionState().configOptions ?? [] });
+                    return;
+                case 'session/prompt':
+                    handlePrompt(id, params);
+                    return;
+                case 'session/cancel':
+                    if (prompt !== null) {
+                        prompt.cancelled = true;
+                        if (permission === null) {
+                            endTurn('cancelled');
+                        }
+                    }
+                    return;
+                default:
+                    if (id !== undefined) {
+                        refuse(id, -32601, `Method not found: ${String(frame.method)}`);
+                    }
+            }
+        };
+
+        return {
+            onLine: (line) => {
+                handle(JSON.parse(line) as Frame);
+            }
+        };
+    };
+}
+
+export const fakeAcp: FakeCli = fakeAcpWith({});

package/src/testing/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 { type FakeIo, type FakeProgram, type FakeCli, type StartedFake, type InProcessCli, inProcess, runOverStdio } from './fake-cli.ts';
+export { type FakeAcpOptions, fakeAcpWith, fakeAcp } from './fake-acp.ts';
 export { fakeClaude, claudeStoppingOnResume } from './fake-claude.ts';
 export { FAKE_CHILD_STEPS, fakeCodexForks, type FakeCodexOptions, fakeCodexWith, fakeCodex } from './fake-codex.ts';
 export { testAccounts } from './accounts.ts';

package/src/usage/index-file.ts

@@ -1,4 +1,4 @@
-import type { UsageProvider } from '@adecore/agent-contracts';
+import { UsageProviderSchema, type UsageProvider } from '@adecore/agent-contracts';
 import type { UsageRecord } from './record.ts';
 import type { CodexParserState } from './readers/codex.ts';
 
@@ -147,7 +147,8 @@ export function decodeIndex(text: string): UsageIndex {
     const accounts = Array.isArray(document.accounts) ? document.accounts : [];
     const name = (table: string[], at: number): string | null => (typeof table[at] === 'string' ? table[at] : null);
     for (const [path, file] of Object.entries(document.files ?? {})) {
-        if (file.p !== 'claude' && file.p !== 'codex') {
+        // Every provider the schema knows, so a new one is never dropped from the index it was saved in.
+        if (!UsageProviderSchema.safeParse(file.p).success) {
             continue;
         }
         if (typeof file.s !== 'number' || typeof file.m !== 'number' || typeof file.o !== 'number' || file.o < 0 || !Array.isArray(file.r)) {

package/src/usage/index.ts

@@ -1,9 +1,10 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
 export { usageAccountsOf, usageRootsOf, limitAccountsOf, chatSessionAccounts } from './accounts.ts';
 export { UsageMonitor, type ProbeEnv, type LimitAccount, type LimitAccounts, type UsageMonitorOptions } from './limits/monitor.ts';
-export type { LimitsUpdate, ProviderReading } from './limits/normalize.ts';
+export { fraction, type LimitsUpdate, type ProviderReading } from './limits/normalize.ts';
 export type { ProbeResult } from './limits/probe.ts';
 export { LITELLM_URL } from './pricing.ts';
+export { hostUsageLine, type HostUsageEntry } from './readers/host-log.ts';
 export type { KnownProject } from './projects.ts';
 export { type UsageRootPath, usageRoots } from './roots.ts';
 export type { UsageScannerOptions } from './scanner.ts';

package/src/usage/limits/monitor.ts

@@ -1,4 +1,4 @@
-import type { UsageLimitsProvider, UsageLimitsSnapshot, UsageProvider } from '@adecore/agent-contracts';
+import { USAGE_PROVIDERS, type UsageLimitsProvider, type UsageLimitsSnapshot, type UsageProvider } from '@adecore/agent-contracts';
 import type { CodexClientInfo } from '../../chat/codex-transport.ts';
 import { ClientSinks } from '../../client-sinks.ts';
 import { errorText } from '../../error-text.ts';
@@ -14,7 +14,7 @@ const MAX_BACKOFF_MS = 60 * 60_000;
 /* An account other than the default one that nobody started a CLI under for this long is only read when a person asks. */
 const RECENT_USE_MS = 24 * 60 * 60_000;
 
-const PROVIDERS: readonly UsageProvider[] = ['claude', 'codex'];
+const PROVIDERS: readonly UsageProvider[] = USAGE_PROVIDERS;
 
 export type ProbeEnv = Record<string, string>;
 
@@ -62,6 +62,12 @@ export interface UsageMonitorOptions {
     accounts?: LimitAccounts;
     /* How to ask; a test answers without starting a CLI. */
     probe?: (kind: UsageProvider, command: readonly string[], env: ProbeEnv) => Promise<ProbeResult>;
+    /*
+     * A plan the host reads itself, for a provider with no CLI to ask (a subscription API the host calls with
+     * its own key). It answers in place of the probe, with no environment and no check that a CLI is installed:
+     * what it says is the whole story, a missing key included.
+     */
+    plans?: Partial<Record<UsageProvider, () => Promise<ProbeResult>>>;
     now?: () => number;
     // How the host names itself to the app-server a probe opens.
     client?: CodexClientInfo;
@@ -71,12 +77,14 @@ export interface UsageMonitorOptions {
  * What is left of each plan, per account. Two sources feed it: a read of our own every five minutes,
  * which starts the CLI, asks and ends it, and the events a running turn streams in between, which
  * cost nothing and arrive the moment a number moves. Neither reads a credential: both CLIs already
- * hold their own login and answer the question themselves.
+ * hold their own login and answer the question themselves. A provider without a CLI is read by the
+ * host that holds its key (`plans`), on the same clock.
  */
 export class UsageMonitor {
     private readonly registry: ProviderRegistry;
     private readonly accounts: LimitAccounts | null;
     private readonly probe: NonNullable<UsageMonitorOptions['probe']>;
+    private readonly plans: NonNullable<UsageMonitorOptions['plans']>;
     private readonly now: () => number;
     private readonly sinks = new ClientSinks<AgentEvent>();
     // By account id, so the default account of a CLI is under the CLI's kind.
@@ -87,6 +95,7 @@ export class UsageMonitor {
     constructor(options: UsageMonitorOptions) {
         this.registry = options.providers;
         this.accounts = options.accounts ?? null;
+        this.plans = options.plans ?? {};
         this.probe = options.probe ?? ((kind, command, env) => (kind === 'claude' ? probeClaude(command, env) : probeCodex(command, env, options.client)));
         this.now = options.now ?? Date.now;
         for (const kind of PROVIDERS) {
@@ -197,16 +206,18 @@ export class UsageMonitor {
                 continue;
             }
             const info = installed.find((provider) => provider.kind === kind);
-            if (info === undefined || !info.installed) {
+            if (this.plans[kind] === undefined && (info === undefined || !info.installed)) {
                 state.published = { ...blank(kind), checkedAt: this.now(), unavailable: { reason: 'not-installed', message: null } };
                 state.nextAt = this.now() + PROBE_INTERVAL_MS;
                 changed = true;
                 continue;
             }
+            // The next read is counted from when this one started, so a read that takes a few seconds does not push the tick of the clock past its time.
+            const startedAt = this.now();
             const result = await this.read(account);
             const failed = 'unavailable' in result && result.unavailable?.reason === 'failed';
             state.backoffMs = failed ? Math.min(MAX_BACKOFF_MS, state.backoffMs * 2) : PROBE_INTERVAL_MS;
-            state.nextAt = this.now() + state.backoffMs;
+            state.nextAt = startedAt + state.backoffMs;
             if (failed && state.published.windows.length > 0) {
                 // A pass that could not reach the CLI leaves the last good numbers where they are.
                 continue;
@@ -223,6 +234,14 @@ export class UsageMonitor {
     }
 
     private async read(account: LimitAccount): Promise<ProbeResult> {
+        const plan = this.plans[account.kind];
+        if (plan !== undefined) {
+            try {
+                return await plan();
+            } catch (e) {
+                return { unavailable: { reason: 'failed', message: errorText(e) } };
+            }
+        }
         let env: ProbeEnv;
         try {
             env = this.accounts === null ? definedEnv(process.env) : this.accounts.envFor(account.kind, account.id);

package/src/usage/limits/normalize.ts

@@ -26,7 +26,8 @@ function num(value: unknown): number | null {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
 
-function fraction(value: number): number {
+/* A share of a plan used, held to the bar: a provider may report more than all of it. */
+export function fraction(value: number): number {
     return Math.min(1, Math.max(0, value));
 }
 

package/src/usage/readers/host-log.ts

@@ -0,0 +1,72 @@
+import type { UsageProvider } from '@adecore/agent-contracts';
+import { asObject, asString, int, type UsageRecord } from '../record.ts';
+
+/*
+ * One call to an API a host makes itself, a line of the usage log it keeps. Such an API has no CLI and so
+ * no transcript, so the host writes this line for each call and the scanner reads the folder like one.
+ * The kinds are disjoint, as they are in a record: `input` is what was neither read from nor written to
+ * a cache, and `reasoning` is a part of `output`. Each host maps the counts of its own API onto them, since
+ * the APIs do not agree: some report a prompt that holds its cached part, some report the input apart from both
+ * cache kinds, and only some have a cache write at all.
+ */
+export interface HostUsageEntry {
+    at: number;
+    model: string;
+    session: string;
+    cwd: string;
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+
+export function hostUsageLine(entry: HostUsageEntry): string {
+    return `${JSON.stringify(entry)}\n`;
+}
+
+/* A line of this log names its model, which keeps `JSON.parse` off anything else a folder holds. */
+export function hostLogMightCarryUsage(line: string): boolean {
+    return line.includes('"model"');
+}
+
+/* The provider is the root's, so one reader serves every API a host logs. */
+export function parseHostUsageLine(line: string, provider: UsageProvider): UsageRecord | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(line);
+    } catch {
+        return null;
+    }
+    const entry = asObject(parsed);
+    if (entry === null) {
+        return null;
+    }
+    const model = asString(entry.model);
+    const timestampMs = typeof entry.at === 'number' && Number.isFinite(entry.at) ? entry.at : Number.NaN;
+    if (model === '' || Number.isNaN(timestampMs)) {
+        return null;
+    }
+    const totals = {
+        calls: 1,
+        input: int(entry.input),
+        cacheRead: int(entry.cacheRead),
+        cacheWrite: int(entry.cacheWrite),
+        cacheWrite1h: 0,
+        output: int(entry.output),
+        reasoning: int(entry.reasoning)
+    };
+    if (totals.input + totals.cacheRead + totals.cacheWrite + totals.output === 0) {
+        return null;
+    }
+    return {
+        provider,
+        timestampMs,
+        model,
+        sessionId: asString(entry.session),
+        cwd: asString(entry.cwd),
+        totals,
+        // Every line is a call of its own, so nothing is folded.
+        dedupeKey: null
+    };
+}

package/src/usage/roots.ts

@@ -9,8 +9,8 @@ export interface UsageRootPath {
     accounts?: string[];
 }
 
-/* Where in its config folder each CLI leaves its transcripts. */
-const TRANSCRIPTS: Record<UsageProvider, string> = { claude: 'projects', codex: 'sessions' };
+/* Where in its config folder each CLI leaves its transcripts. A provider with no CLI has a log its host passes as a root of its own. */
+const TRANSCRIPTS: Partial<Record<UsageProvider, string>> & Record<'claude' | 'codex', string> = { claude: 'projects', codex: 'sessions' };
 
 /* The transcripts of the default accounts, found through the variables the CLIs themselves read. */
 export function usageRoots(env: Record<string, string | undefined> = process.env): UsageRootPath[] {
@@ -25,7 +25,11 @@ export function usageRoots(env: Record<string, string | undefined> = process.env
 export function accountRoots(folders: ReadonlyArray<{ id: string; kind: UsageProvider; folder: string }>): UsageRootPath[] {
     const roots = new Map<string, UsageRootPath & { accounts: string[] }>();
     for (const { id, kind, folder } of folders) {
-        const path = join(folder, TRANSCRIPTS[kind]);
+        const transcripts = TRANSCRIPTS[kind];
+        if (transcripts === undefined) {
+            continue;
+        }
+        const path = join(folder, transcripts);
         const key = `${kind}\0${path}`;
         const root = roots.get(key);
         if (root === undefined) {