@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/providers/claude.js

@@ -0,0 +1,105 @@
+// Base arguments for a chat process; the session adds what the selection and the modes ask for.
+const CLAUDE_CHAT_ARGS = [
+    '-p',
+    '--output-format',
+    'stream-json',
+    '--input-format',
+    'stream-json',
+    '--verbose',
+    '--include-partial-messages',
+    '--replay-user-messages',
+    '--permission-prompt-tool',
+    'stdio'
+];
+// Effort values the CLI takes on its flag; anything else is asked for in the prompt instead.
+const FLAG_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+const PERMISSION_MODE = {
+    supervised: null,
+    'auto-accept-edits': 'acceptEdits',
+    auto: 'auto',
+    'full-access': 'bypassPermissions'
+};
+export function claudeRuntimeMode(mode) {
+    if (mode === 'default') {
+        return 'supervised';
+    }
+    return Object.keys(PERMISSION_MODE).find((key) => PERMISSION_MODE[key] === mode);
+}
+/* The argument list for one Claude Code chat process. */
+export function claudeArgs(launch) {
+    // The `=` form matters, since the flag is variadic and would swallow a prompt argument after it (measured on Claude Code 2.1.274).
+    const args = [
+        ...CLAUDE_CHAT_ARGS,
+        ...(launch.allowedTools ?? []).map((tool) => `--allowedTools=${tool}`),
+        ...(launch.folders ?? []).map((folder) => `--add-dir=${folder}`)
+    ];
+    const contextWindow = launch.selection.options.contextWindow;
+    args.push('--model', `${launch.selection.model}${contextWindow === '1m' ? '[1m]' : ''}`);
+    const effort = launch.selection.options.effort;
+    if (typeof effort === 'string' && FLAG_EFFORTS.has(effort)) {
+        args.push('--effort', effort);
+    }
+    /*
+     * Fast mode has no flag of its own; the CLI reads it from the settings blob, which is also the
+     * opt-in the init frame asks for (without it the frame answers `sdk_opt_in_required`). It only
+     * takes on a model that offers it, so the catalog puts the option on those models alone.
+     * A 200k pick turns auto-compact on over the person's own setting, since `claudeEnv` only moves
+     * where it compacts and a CLI under `-p` never stops at a window (measured on Claude Code 2.1.283).
+     */
+    const settings = {
+        ...(launch.selection.options.fastMode === true ? { fastMode: true } : {}),
+        ...(launch.selection.options.contextWindow === '200k' ? { autoCompactEnabled: true } : {})
+    };
+    if (Object.keys(settings).length > 0) {
+        args.push('--settings', JSON.stringify(settings));
+    }
+    const permissionMode = PERMISSION_MODE[launch.runtimeMode];
+    if (permissionMode) {
+        args.push('--permission-mode', permissionMode);
+    }
+    if (permissionMode === 'bypassPermissions') {
+        args.push('--allow-dangerously-skip-permissions');
+    }
+    if (launch.resume) {
+        args.push('--resume', launch.resume);
+    }
+    return args;
+}
+/*
+ * Leaving out `[1m]` does not cap a model the CLI runs natively on 1M on a subscription (Fable,
+ * Opus 5.5, Sonnet 5), and `autoCompactWindow` in `--settings` is ignored under `-p`: only this
+ * variable holds a 200k pick (measured on Claude Code 2.1.280). It holds it only with auto-compact
+ * on, which `claudeArgs` sees to.
+ */
+export function claudeEnv(selection) {
+    return selection.options.contextWindow === '200k' ? { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '200000' } : {};
+}
+// What the CLI can do, as far as a client has to know.
+export const CLAUDE_CAPABILITIES = {
+    chat: true,
+    terminal: true,
+    hooks: true,
+    streamsToolOutput: false,
+    diffs: 'before-after',
+    attachments: true,
+    mentions: true,
+    denyReason: true,
+    allowAlways: true,
+    asyncQuestions: false,
+    compaction: 'prompt',
+    reportsCost: true,
+    /*
+     * The CLI's `modelUsage.contextWindow` is the model's maximum, not the window a 200k pick compacts at:
+     * a run started without `[1m]` reports 1000000 too (measured on Claude Code 2.1.274). The catalog
+     * knows what the pick asked for, so the meter reads that and nothing here reports a window.
+     */
+    reportsContextWindow: false,
+    reportsThinking: true,
+    slashCommands: true
+};
+// Claude Code takes its flags before `--resume`, which takes the id.
+export const CLAUDE_RESUME_COMMAND = 'claude {flags} --resume {id}';
+/* Words the model reads as instructions, prepended to the prompt for options the CLI has no flag for. */
+export function promptPrefix(selection) {
+    return selection.options.effort === 'ultrathink' ? 'ultrathink\n\n' : '';
+}

package/dist/providers/codex-models.json

@@ -0,0 +1,135 @@
+{
+  "updatedAt": "2026-09-29T17:26:43Z",
+  "defaultModel": "gpt-6-astra",
+  "profiles": {
+    "ultra": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "medium",
+          "choices": [
+            { "id": "low", "label": "Low", "description": "Fast responses with lighter reasoning" },
+            { "id": "medium", "label": "Medium", "description": "Balances speed and reasoning depth for everyday tasks" },
+            { "id": "high", "label": "High", "description": "Greater reasoning depth for complex problems" },
+            { "id": "xhigh", "label": "Extra high", "description": "Extra high reasoning depth for complex problems" },
+            { "id": "max", "label": "Max", "description": "Maximum reasoning depth for the hardest problems" },
+            { "id": "ultra", "label": "Ultra", "description": "Maximum reasoning with automatic task delegation" }
+          ]
+        },
+        {
+          "id": "serviceTier",
+          "label": "Priority",
+          "type": "boolean",
+          "defaultValue": false,
+          "description": "Faster answers on the priority tier, at a higher usage cost"
+        }
+      ],
+      "contextWindowTokens": { "*": 258400 }
+    },
+    "ultra-low": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "low",
+          "choices": [
+            { "id": "low", "label": "Low", "description": "Fast responses with lighter reasoning" },
+            { "id": "medium", "label": "Medium", "description": "Balances speed and reasoning depth for everyday tasks" },
+            { "id": "high", "label": "High", "description": "Greater reasoning depth for complex problems" },
+            { "id": "xhigh", "label": "Extra high", "description": "Extra high reasoning depth for complex problems" },
+            { "id": "max", "label": "Max", "description": "Maximum reasoning depth for the hardest problems" },
+            { "id": "ultra", "label": "Ultra", "description": "Maximum reasoning with automatic task delegation" }
+          ]
+        },
+        {
+          "id": "serviceTier",
+          "label": "Priority",
+          "type": "boolean",
+          "defaultValue": false,
+          "description": "Faster answers on the priority tier, at a higher usage cost"
+        }
+      ],
+      "contextWindowTokens": { "*": 258400 }
+    },
+    "max": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "medium",
+          "choices": [
+            { "id": "low", "label": "Low", "description": "Fast responses with lighter reasoning" },
+            { "id": "medium", "label": "Medium", "description": "Balances speed and reasoning depth for everyday tasks" },
+            { "id": "high", "label": "High", "description": "Greater reasoning depth for complex problems" },
+            { "id": "xhigh", "label": "Extra high", "description": "Extra high reasoning depth for complex problems" },
+            { "id": "max", "label": "Max", "description": "Maximum reasoning depth for the hardest problems" }
+          ]
+        },
+        {
+          "id": "serviceTier",
+          "label": "Priority",
+          "type": "boolean",
+          "defaultValue": false,
+          "description": "Faster answers on the priority tier, at a higher usage cost"
+        }
+      ],
+      "contextWindowTokens": { "*": 258400 }
+    },
+    "xhigh": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "medium",
+          "choices": [
+            { "id": "low", "label": "Low", "description": "Fast responses with lighter reasoning" },
+            { "id": "medium", "label": "Medium", "description": "Balances speed and reasoning depth for everyday tasks" },
+            { "id": "high", "label": "High", "description": "Greater reasoning depth for complex problems" },
+            { "id": "xhigh", "label": "Extra high", "description": "Extra high reasoning depth for complex problems" }
+          ]
+        },
+        {
+          "id": "serviceTier",
+          "label": "Priority",
+          "type": "boolean",
+          "defaultValue": false,
+          "description": "Faster answers on the priority tier, at a higher usage cost"
+        }
+      ],
+      "contextWindowTokens": { "*": 258400 }
+    },
+    "spark": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "high",
+          "choices": [
+            { "id": "low", "label": "Low", "description": "Fast responses with lighter reasoning" },
+            { "id": "medium", "label": "Medium", "description": "Balances speed and reasoning depth for everyday tasks" },
+            { "id": "high", "label": "High", "description": "Greater reasoning depth for complex problems" },
+            { "id": "xhigh", "label": "Extra high", "description": "Extra high reasoning depth for complex problems" }
+          ]
+        }
+      ],
+      "contextWindowTokens": { "*": 121600 }
+    }
+  },
+  "models": [
+    { "slug": "gpt-6-astra", "name": "GPT-6 Astra", "profile": "ultra", "aliases": ["astra", "gpt-6"] },
+    { "slug": "gpt-6.1-sol", "name": "GPT-6.1 Sol", "badge": "new", "profile": "max", "aliases": ["sol"] },
+    { "slug": "gpt-6-sol", "name": "GPT-6 Sol", "profile": "max" },
+    { "slug": "gpt-6-luna", "name": "GPT-6 Luna", "badge": "new", "profile": "max", "aliases": ["luna"] },
+    { "slug": "gpt-5.6-sol", "name": "GPT-5.6 Sol", "profile": "ultra-low", "legacy": true },
+    { "slug": "gpt-5.6-terra", "name": "GPT-5.6 Terra", "profile": "ultra", "aliases": ["terra"], "badge": "retiring", "legacy": true },
+    { "slug": "gpt-5.6-luna", "name": "GPT-5.6 Luna", "profile": "max", "legacy": true },
+    { "slug": "gpt-5.5", "name": "GPT-5.5", "profile": "xhigh", "legacy": true },
+    { "slug": "gpt-5.3-codex-spark", "name": "GPT-5.3 Codex Spark", "profile": "spark", "aliases": ["spark"], "legacy": true }
+  ]
+}

package/dist/providers/codex-provider.d.ts

@@ -0,0 +1,4 @@
+import { type CodexBackendOptions } from '../chat/codex-backend.ts';
+import type { ChatProvider } from './provider.ts';
+export declare function createCodexProvider(options?: CodexBackendOptions): ChatProvider;
+export declare const codexProvider: ChatProvider;

package/dist/providers/codex-provider.js

@@ -0,0 +1,27 @@
+import { CodexBackend } from '../chat/codex-backend.js';
+import { ModelCatalog } from './catalog.js';
+import { CODEX_CAPABILITIES, CODEX_CHAT_ARGS, CODEX_RESUME_COMMAND } from './codex.js';
+import codexManifest from './codex-models.json' with { type: 'json' };
+import { detectCli } from './detect.js';
+export function createCodexProvider(options = {}) {
+    return {
+        kind: 'codex',
+        name: 'Codex',
+        catalog: new ModelCatalog(codexManifest),
+        capabilities: CODEX_CAPABILITIES,
+        command: ['codex', ...CODEX_CHAT_ARGS],
+        resumeCommand: CODEX_RESUME_COMMAND,
+        // The auth variables Codex 0.157 names in its own "no Codex credentials were found" advice.
+        home: { env: 'CODEX_HOME', fallback: '.codex', loginEnv: ['OPENAI_API_KEY', 'CODEX_API_KEY', 'CODEX_ACCESS_TOKEN'], loginCommand: 'codex login' },
+        detect: detectCli,
+        // Read-only and without an approval to wait for: the run only has to read what it is handed. A chat's
+        // title is asked in a folder that need not be a repository, and ephemeral keeps the run out of Codex's thread list.
+        oneShotArgs: (prompt) => ['exec', '--color', 'never', '--sandbox', 'read-only', '--skip-git-repo-check', '--ephemeral', prompt],
+        // A prompt of `-` is read from stdin.
+        oneShotStdinArgs: ['exec', '--color', 'never', '--sandbox', 'read-only', '--skip-git-repo-check', '--ephemeral', '-'],
+        // `codex [OPTIONS] [PROMPT]`: the positional starts the interactive session on that prompt.
+        firstPromptArgs: (prompt) => [prompt],
+        createBackend: (launch, host) => new CodexBackend(launch, host, options)
+    };
+}
+export const codexProvider = createCodexProvider();

package/dist/providers/codex-rules.d.ts

@@ -0,0 +1,9 @@
+export interface CodexRules {
+    app: string;
+    commands: readonly string[];
+}
+export type CodexRulesResult = 'unchanged' | 'written';
+export declare function codexRulesText(rules: CodexRules): string;
+export declare function codexRulesPathIn(folder: string, rules: CodexRules): string;
+export declare function defaultCodexHome(env?: Record<string, string | undefined>): string;
+export declare function installCodexRules(path: string, rules: CodexRules): Promise<CodexRulesResult>;

package/dist/providers/codex-rules.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { errorText } from '../error-text.js';
+import { isNotFound, writeAtomic } from '../fs.js';
+export function codexRulesText(rules) {
+    return ([
+        `# Written by ${rules.app}; it is rewritten when it changes.`,
+        ...rules.commands.map((command) => `prefix_rule(pattern=[${JSON.stringify(command)}], decision="allow")`)
+    ].join('\n') + '\n');
+}
+// Codex loads every `*.rules` file in the `rules` folder of its home, and only from there, never from a flag.
+export function codexRulesPathIn(folder, rules) {
+    return join(folder, 'rules', `${rules.app.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.rules`);
+}
+export function defaultCodexHome(env = process.env) {
+    return env.CODEX_HOME ?? join(env.HOME ?? homedir(), '.codex');
+}
+/* Idempotent: a file that already says the same is left alone. */
+export async function installCodexRules(path, rules) {
+    const text = codexRulesText(rules);
+    try {
+        if ((await readFile(path, 'utf8')) === text) {
+            return 'unchanged';
+        }
+    }
+    catch (e) {
+        if (!isNotFound(e)) {
+            throw new Error(`Cannot read ${path}: ${errorText(e)}`);
+        }
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeAtomic(path, text, 0o644);
+    return 'written';
+}

package/dist/providers/codex.d.ts

@@ -0,0 +1,14 @@
+import type { ModelSelection, ProviderCapabilities, RuntimeMode } from '@adecore/agent-contracts';
+export declare const CODEX_CHAT_ARGS: string[];
+type CodexApprovalPolicy = 'untrusted' | 'on-request' | 'never';
+type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+interface CodexThreadOptions {
+    approvalPolicy: CodexApprovalPolicy;
+    sandbox: CodexSandboxMode;
+}
+export declare function codexThreadOptions(runtimeMode: RuntimeMode): CodexThreadOptions;
+export declare function codexRuntimeMode(approvalPolicy: string, sandbox: string): RuntimeMode | undefined;
+export declare function codexServiceTier(selection: ModelSelection): string | null;
+export declare const CODEX_CAPABILITIES: ProviderCapabilities;
+export declare const CODEX_RESUME_COMMAND = "codex resume {flags} {id}";
+export {};

package/dist/providers/codex.js

@@ -0,0 +1,52 @@
+// The app-server speaks JSON-RPC on stdio; the session adds nothing to the command line.
+export const CODEX_CHAT_ARGS = ['app-server'];
+/*
+ * Codex has two knobs, when it asks and where it may write, and no "ask for commands but not for
+ * edits" policy. `untrusted` inside a writable workspace comes closest: edits within the workspace
+ * pass the sandbox without a prompt, commands still ask unless Codex knows them as safe.
+ * `on-request` with the same sandbox is Codex's own default and stands in for `auto`.
+ */
+const THREAD_OPTIONS = {
+    supervised: { approvalPolicy: 'untrusted', sandbox: 'read-only' },
+    'auto-accept-edits': { approvalPolicy: 'untrusted', sandbox: 'workspace-write' },
+    auto: { approvalPolicy: 'on-request', sandbox: 'workspace-write' },
+    'full-access': { approvalPolicy: 'never', sandbox: 'danger-full-access' }
+};
+export function codexThreadOptions(runtimeMode) {
+    return THREAD_OPTIONS[runtimeMode];
+}
+export function codexRuntimeMode(approvalPolicy, sandbox) {
+    const names = { readOnly: 'read-only', workspaceWrite: 'workspace-write', dangerFullAccess: 'danger-full-access' };
+    return Object.keys(THREAD_OPTIONS).find((mode) => {
+        const options = THREAD_OPTIONS[mode];
+        return options.approvalPolicy === approvalPolicy && options.sandbox === (names[sandbox] ?? sandbox);
+    });
+}
+// What the app-server calls the faster of the two tiers it lists per model; the standard tier is no id at all.
+const CODEX_PRIORITY_TIER = 'priority';
+/* The service tier a thread or a turn runs on, or null for the standard one the account defaults to. */
+export function codexServiceTier(selection) {
+    return selection.options.serviceTier === true ? CODEX_PRIORITY_TIER : null;
+}
+// What the app-server can do, as far as a client has to know.
+export const CODEX_CAPABILITIES = {
+    chat: true,
+    terminal: true,
+    hooks: true,
+    streamsToolOutput: true,
+    diffs: 'unified',
+    attachments: true,
+    // Codex has no mention part in its protocol; the picker sends the path as text, which is all
+    // the model needs to open the file with its own tools.
+    mentions: true,
+    denyReason: false,
+    allowAlways: true,
+    asyncQuestions: true,
+    compaction: 'native',
+    reportsCost: false,
+    reportsContextWindow: true,
+    reportsThinking: true,
+    slashCommands: false
+};
+// `codex resume` is a subcommand that reads `[OPTIONS] [SESSION_ID]`, so the flags go after it.
+export const CODEX_RESUME_COMMAND = 'codex resume {flags} {id}';

package/dist/providers/detect.d.ts

@@ -0,0 +1,6 @@
+import { type SpawnChatProcess } from '../chat/chat-process.ts';
+export interface CliDetection {
+    installed: boolean;
+    version: string | null;
+}
+export declare function detectCli(command: string, env?: Record<string, string | undefined>, spawn?: SpawnChatProcess): Promise<CliDetection>;

package/dist/providers/detect.js

@@ -0,0 +1,30 @@
+import { spawnChatProcess } from '../chat/chat-process.js';
+function definedOnly(env) {
+    const defined = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined) {
+            defined[key] = value;
+        }
+    }
+    return defined;
+}
+/* Asks a CLI for its version; a missing binary is a plain "not installed", never an error. */
+export async function detectCli(command, env = process.env, spawn = spawnChatProcess) {
+    try {
+        let exited = () => undefined;
+        const code = new Promise((resolve) => {
+            exited = resolve;
+        });
+        const proc = spawn({ command: [command, '--version'], cwd: process.cwd(), env: definedOnly(env), onExit: (exitCode) => exited(exitCode) });
+        proc.stdin.end();
+        const output = await new Response(proc.stdout).text();
+        if ((await code) !== 0) {
+            return { installed: false, version: null };
+        }
+        const version = /\d+\.\d+\.\d+/.exec(output)?.[0] ?? output.trim() ?? null;
+        return { installed: true, version };
+    }
+    catch {
+        return { installed: false, version: null };
+    }
+}

package/dist/providers/provider.d.ts

@@ -0,0 +1,25 @@
+import type { AgentKind, ProviderCapabilities } from '@adecore/agent-contracts';
+import type { BackendHost, BackendLaunch, ChatBackend } from '../chat/backend.ts';
+import type { ModelCatalog } from './catalog.ts';
+import type { CliDetection } from './detect.ts';
+export interface ProviderHome {
+    readonly env: string;
+    readonly fallback: string;
+    readonly loginEnv: readonly string[];
+    readonly loginCommand: string;
+}
+export interface ChatProvider {
+    readonly kind: AgentKind;
+    readonly name: string;
+    readonly catalog: ModelCatalog;
+    readonly capabilities: ProviderCapabilities;
+    readonly command: string[];
+    readonly resumeCommand: string;
+    readonly home?: ProviderHome;
+    oneShotArgs?(prompt: string): string[];
+    readonly oneShotStdinArgs?: readonly string[];
+    firstPromptArgs(prompt: string): string[];
+    detect(command: string, env: Record<string, string | undefined>): Promise<CliDetection>;
+    enabled?(): boolean;
+    createBackend(launch: BackendLaunch, host: BackendHost): ChatBackend;
+}

package/dist/providers/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/registry.d.ts

@@ -0,0 +1,28 @@
+import type { AgentKind, ProviderInfo } from '@adecore/agent-contracts';
+import { ModelCatalog } from './catalog.ts';
+import type { CliDetection } from './detect.ts';
+import type { ChatProvider } from './provider.ts';
+export declare function unofferedProvider(kind: AgentKind): ChatProvider;
+export declare function providerFor(kind: AgentKind): ChatProvider;
+export interface ProviderRegistryOptions {
+    providers?: ChatProvider[];
+    commands?: Partial<Record<AgentKind, string>>;
+    detect?: (command: string) => Promise<CliDetection>;
+    env?: Record<string, string | undefined>;
+}
+export declare class ProviderRegistry {
+    private readonly providers;
+    private readonly commands;
+    private readonly detect;
+    private readonly env;
+    private readonly cache;
+    constructor(options?: ProviderRegistryOptions);
+    list(): Promise<ProviderInfo[]>;
+    get(kind: AgentKind): ChatProvider;
+    oneShotProvider(preferred?: AgentKind): Promise<ChatProvider | null>;
+    catalogFor(kind: AgentKind): ModelCatalog;
+    enabled(kind: AgentKind): boolean;
+    invalidate(kind: AgentKind): void;
+    protected fallback(kind: AgentKind): ChatProvider;
+    private detection;
+}

package/dist/providers/registry.js

@@ -0,0 +1,118 @@
+import { ModelCatalog } from './catalog.js';
+import { claudeProvider } from './claude-provider.js';
+import { codexProvider } from './codex-provider.js';
+// How long a "is it installed" answer stays good; an install mid-session shows up on the next check.
+const DETECTION_TTL_MS = 60_000;
+const DISABLED = { installed: false, version: 'Disabled in Settings' };
+const NO_CAPABILITIES = {
+    chat: false,
+    terminal: false,
+    hooks: false,
+    streamsToolOutput: false,
+    diffs: 'none',
+    attachments: false,
+    mentions: false,
+    denyReason: false,
+    allowAlways: false,
+    asyncQuestions: false,
+    compaction: 'none',
+    reportsCost: false,
+    reportsContextWindow: false,
+    reportsThinking: false,
+    slashCommands: false
+};
+/* A CLI of a kind the host does not offer: a record or an account may still name one, and it starts nothing. */
+export function unofferedProvider(kind) {
+    return {
+        kind,
+        name: kind,
+        catalog: new ModelCatalog({ defaultModel: '', profiles: {}, models: [] }),
+        capabilities: NO_CAPABILITIES,
+        command: [kind],
+        resumeCommand: '',
+        detect: () => Promise.resolve({ installed: false, version: null }),
+        firstPromptArgs: () => {
+            throw new Error(`${kind} is not offered here`);
+        },
+        createBackend: () => {
+            throw new Error(`${kind} is not offered here`);
+        }
+    };
+}
+const BUILT_IN_PROVIDERS = [claudeProvider, codexProvider];
+/* The provider of a kind, for the places that have no registry at hand. */
+export function providerFor(kind) {
+    return BUILT_IN_PROVIDERS.find((provider) => provider.kind === kind) ?? unofferedProvider(kind);
+}
+/* What a host knows about each agent CLI: whether it is there, what it offers and what it can do. */
+export class ProviderRegistry {
+    providers;
+    commands;
+    detect;
+    env;
+    cache = new Map();
+    constructor(options = {}) {
+        this.providers = options.providers ?? [...BUILT_IN_PROVIDERS];
+        this.commands = options.commands ?? {};
+        this.detect = options.detect ?? null;
+        this.env = options.env ?? process.env;
+    }
+    async list() {
+        return await Promise.all(this.providers.map(async (provider) => ({
+            kind: provider.kind,
+            name: provider.name,
+            ...(await this.detection(provider)),
+            models: provider.catalog.list(),
+            defaultModel: provider.catalog.defaultModel || null,
+            capabilities: provider.capabilities,
+            resumeCommand: provider.resumeCommand
+        })));
+    }
+    /* The provider of a kind, one this host does not offer included. */
+    get(kind) {
+        return this.providers.find((provider) => provider.kind === kind) ?? this.fallback(kind);
+    }
+    /*
+     * The CLI that answers a single prompt here: the one asked for when it is installed, else the
+     * first installed provider that can, in the order the catalog lists them. Null on a machine
+     * with none, which is what hides the button that would ask.
+     */
+    async oneShotProvider(preferred) {
+        const order = preferred ? [this.get(preferred), ...this.providers] : this.providers;
+        for (const provider of order) {
+            if (provider.oneShotArgs && (await this.detection(provider)).installed) {
+                return provider;
+            }
+        }
+        return null;
+    }
+    catalogFor(kind) {
+        return this.get(kind).catalog;
+    }
+    enabled(kind) {
+        return this.get(kind).enabled?.() !== false;
+    }
+    invalidate(kind) {
+        this.cache.delete(kind);
+    }
+    fallback(kind) {
+        return unofferedProvider(kind);
+    }
+    async detection(provider) {
+        if (provider.enabled?.() === false) {
+            return DISABLED;
+        }
+        const cached = this.cache.get(provider.kind);
+        if (cached && Date.now() - cached.at < DETECTION_TTL_MS) {
+            return cached.detection;
+        }
+        const command = this.commands[provider.kind] ?? provider.command[0];
+        const detection = this.detect ? await this.detect(command) : await provider.detect(command, this.env);
+        // Turned off while the probe ran.
+        if (provider.enabled?.() === false) {
+            return DISABLED;
+        }
+        this.cache.set(provider.kind, { at: Date.now(), detection });
+        return detection;
+    }
+}

package/dist/record-directory.d.ts

@@ -0,0 +1,27 @@
+import type { z } from 'zod';
+export declare function recordFileName(id: string): string;
+export interface RecordDirectoryOptions<T> {
+    dir: string;
+    schema: z.ZodType<T>;
+    idOf(record: T): string;
+    write?: (path: string, text: string) => Promise<void>;
+    keep?(record: T): T | null;
+}
+export declare class RecordDirectory<T> {
+    readonly dir: string;
+    private readonly schema;
+    private readonly idOf;
+    private readonly writeFile;
+    private readonly keep;
+    private readonly records;
+    private readonly writes;
+    constructor(options: RecordDirectoryOptions<T>);
+    load(): Promise<void>;
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    all(): T[];
+    write(record: T): Promise<boolean>;
+    remove(id: string): Promise<void>;
+    prune(drop: (record: T) => boolean): Promise<void>;
+    private pathOf;
+}