@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/providers/claude-models.json

@@ -0,0 +1,114 @@
+{
+  "updatedAt": "2026-09-28T19:00:00Z",
+  "defaultModel": "claude-sonnet-5-5",
+  "profiles": {
+    "frontier": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "high",
+          "choices": [
+            { "id": "low", "label": "Low" },
+            { "id": "medium", "label": "Medium" },
+            { "id": "high", "label": "High" },
+            { "id": "xhigh", "label": "Extra high" },
+            { "id": "max", "label": "Max" },
+            { "id": "ultrathink", "label": "Ultrathink", "description": "Asks for the longest thinking in the prompt itself" }
+          ]
+        },
+        {
+          "id": "contextWindow",
+          "label": "Context window",
+          "type": "select",
+          "defaultChoice": "1m",
+          "choices": [
+            { "id": "200k", "label": "200k" },
+            { "id": "1m", "label": "1M" }
+          ]
+        }
+      ],
+      "contextWindowTokens": { "200k": 200000, "1m": 1000000 }
+    },
+    "opus": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "high",
+          "choices": [
+            { "id": "low", "label": "Low" },
+            { "id": "medium", "label": "Medium" },
+            { "id": "high", "label": "High" },
+            { "id": "xhigh", "label": "Extra high" },
+            { "id": "max", "label": "Max" },
+            { "id": "ultrathink", "label": "Ultrathink", "description": "Asks for the longest thinking in the prompt itself" }
+          ]
+        },
+        {
+          "id": "contextWindow",
+          "label": "Context window",
+          "type": "select",
+          "defaultChoice": "1m",
+          "choices": [
+            { "id": "200k", "label": "200k" },
+            { "id": "1m", "label": "1M" }
+          ]
+        },
+        {
+          "id": "fastMode",
+          "label": "Fast mode",
+          "type": "boolean",
+          "defaultValue": false,
+          "description": "Answers sooner and spends usage faster"
+        }
+      ],
+      "contextWindowTokens": { "200k": 200000, "1m": 1000000 }
+    },
+    "sonnet": {
+      "options": [
+        {
+          "id": "effort",
+          "label": "Reasoning",
+          "type": "select",
+          "defaultChoice": "high",
+          "choices": [
+            { "id": "low", "label": "Low" },
+            { "id": "medium", "label": "Medium" },
+            { "id": "high", "label": "High" },
+            { "id": "xhigh", "label": "Extra high" },
+            { "id": "max", "label": "Max" },
+            { "id": "ultrathink", "label": "Ultrathink", "description": "Asks for the longest thinking in the prompt itself" }
+          ]
+        },
+        {
+          "id": "contextWindow",
+          "label": "Context window",
+          "type": "select",
+          "defaultChoice": "200k",
+          "choices": [
+            { "id": "200k", "label": "200k" },
+            { "id": "1m", "label": "1M" }
+          ]
+        }
+      ],
+      "contextWindowTokens": { "200k": 200000, "1m": 1000000 }
+    },
+    "haiku": {
+      "options": [{ "id": "thinking", "label": "Thinking", "type": "boolean", "defaultValue": true }],
+      "contextWindowTokens": { "*": 200000 }
+    }
+  },
+  "models": [
+    { "slug": "claude-fable-5-1", "name": "Claude Fable 5.1", "profile": "frontier", "aliases": ["fable"] },
+    { "slug": "claude-opus-5-5", "name": "Claude Opus 5.5", "badge": "new", "profile": "opus", "aliases": ["opus"] },
+    { "slug": "claude-opus-5", "name": "Claude Opus 5", "profile": "opus" },
+    { "slug": "claude-sonnet-5-5", "name": "Claude Sonnet 5.5", "badge": "new", "profile": "sonnet", "aliases": ["sonnet"] },
+    { "slug": "claude-sonnet-5", "name": "Claude Sonnet 5", "profile": "sonnet" },
+    { "slug": "claude-haiku-4-5", "name": "Claude Haiku 4.5", "profile": "haiku", "aliases": ["haiku"] },
+    { "slug": "claude-opus-4-6", "name": "Claude Opus 4.6", "profile": "frontier", "legacy": true },
+    { "slug": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6", "profile": "sonnet", "legacy": true }
+  ]
+}

package/src/providers/claude-provider.ts

@@ -0,0 +1,32 @@
+import { ClaudeBackend, type ClaudeBackendOptions } from '../chat/claude-backend.ts';
+import { ModelCatalog } from './catalog.ts';
+import { CLAUDE_CAPABILITIES, CLAUDE_RESUME_COMMAND } from './claude.ts';
+import { detectCli } from './detect.ts';
+import type { ChatProvider } from './provider.ts';
+
+export function createClaudeProvider(options: ClaudeBackendOptions = {}): ChatProvider {
+    return {
+        kind: 'claude',
+        name: 'Claude Code',
+        catalog: new ModelCatalog(),
+        capabilities: CLAUDE_CAPABILITIES,
+        command: ['claude'],
+        resumeCommand: CLAUDE_RESUME_COMMAND,
+        // Read from the strings of Claude Code 2.1.282; never HOME, which moves the keychain lookup along with it.
+        home: {
+            env: 'CLAUDE_CONFIG_DIR',
+            fallback: '.claude',
+            loginEnv: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN'],
+            loginCommand: 'claude auth login'
+        },
+        detect: detectCli,
+        oneShotArgs: (prompt) => ['-p', prompt, '--output-format', 'text'],
+        // `-p` without a prompt argument reads the prompt from stdin.
+        oneShotStdinArgs: ['-p', '--output-format', 'text'],
+        // `claude [options] [prompt]`: the prompt is the positional, and without -p the session stays.
+        firstPromptArgs: (prompt) => [prompt],
+        createBackend: (launch, host) => new ClaudeBackend(launch, host, options)
+    };
+}
+
+export const claudeProvider = createClaudeProvider();

package/src/providers/claude.ts

@@ -0,0 +1,123 @@
+import type { ModelSelection, ProviderCapabilities, RuntimeMode } from '@adecore/agent-contracts';
+
+// 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: Record<RuntimeMode, string | null> = {
+    supervised: null,
+    'auto-accept-edits': 'acceptEdits',
+    auto: 'auto',
+    'full-access': 'bypassPermissions'
+};
+
+export function claudeRuntimeMode(mode: string): RuntimeMode | undefined {
+    if (mode === 'default') {
+        return 'supervised';
+    }
+    return (Object.keys(PERMISSION_MODE) as RuntimeMode[]).find((key) => PERMISSION_MODE[key] === mode);
+}
+
+interface ClaudeLaunch {
+    selection: ModelSelection;
+    runtimeMode: RuntimeMode;
+    resume: string | null;
+    allowedTools?: readonly string[];
+    folders?: readonly string[];
+}
+
+/* The argument list for one Claude Code chat process. */
+export function claudeArgs(launch: ClaudeLaunch): string[] {
+    // 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: ModelSelection): Record<string, string> {
+    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: ProviderCapabilities = {
+    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: ModelSelection): string {
+    return selection.options.effort === 'ultrathink' ? 'ultrathink\n\n' : '';
+}

package/src/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/src/providers/codex-provider.ts

@@ -0,0 +1,30 @@
+import { CodexBackend, type CodexBackendOptions } from '../chat/codex-backend.ts';
+import { ModelCatalog } from './catalog.ts';
+import { CODEX_CAPABILITIES, CODEX_CHAT_ARGS, CODEX_RESUME_COMMAND } from './codex.ts';
+import codexManifest from './codex-models.json' with { type: 'json' };
+import { detectCli } from './detect.ts';
+import type { ChatProvider } from './provider.ts';
+
+export function createCodexProvider(options: CodexBackendOptions = {}): ChatProvider {
+    return {
+        kind: 'codex',
+        name: 'Codex',
+        catalog: new ModelCatalog(codexManifest as never),
+        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/src/providers/codex-rules.ts

@@ -0,0 +1,54 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { errorText } from '../error-text.ts';
+import { isNotFound, writeAtomic } from '../fs.ts';
+
+/*
+ * The commands a host lets Codex run outside its sandbox without asking: the seatbelt of
+ * workspace-write blocks every socket, loopback included, and Codex 0.157 has no setting that opens
+ * only the one a host's context CLI posts to. Opening the network for the whole sandbox would let
+ * every command out; this lets out only the named ones, which the host enforces on its side.
+ */
+export interface CodexRules {
+    /* Names the file and says who wrote it, so a person's `default.rules` is never touched. */
+    app: string;
+    commands: readonly string[];
+}
+
+export type CodexRulesResult = 'unchanged' | 'written';
+
+export function codexRulesText(rules: CodexRules): string {
+    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: string, rules: CodexRules): string {
+    return join(folder, 'rules', `${rules.app.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.rules`);
+}
+
+export function defaultCodexHome(env: Record<string, string | undefined> = process.env): string {
+    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: string, rules: CodexRules): Promise<CodexRulesResult> {
+    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/src/providers/codex.ts

@@ -0,0 +1,69 @@
+import type { ModelSelection, ProviderCapabilities, RuntimeMode } from '@adecore/agent-contracts';
+
+// The app-server speaks JSON-RPC on stdio; the session adds nothing to the command line.
+export const CODEX_CHAT_ARGS = ['app-server'];
+
+type CodexApprovalPolicy = 'untrusted' | 'on-request' | 'never';
+type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+
+interface CodexThreadOptions {
+    approvalPolicy: CodexApprovalPolicy;
+    sandbox: CodexSandboxMode;
+}
+
+/*
+ * 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: Record<RuntimeMode, CodexThreadOptions> = {
+    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: RuntimeMode): CodexThreadOptions {
+    return THREAD_OPTIONS[runtimeMode];
+}
+
+export function codexRuntimeMode(approvalPolicy: string, sandbox: string): RuntimeMode | undefined {
+    const names: Record<string, string> = { readOnly: 'read-only', workspaceWrite: 'workspace-write', dangerFullAccess: 'danger-full-access' };
+    return (Object.keys(THREAD_OPTIONS) as RuntimeMode[]).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: ModelSelection): string | null {
+    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: ProviderCapabilities = {
+    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/src/providers/detect.ts

@@ -0,0 +1,40 @@
+import { spawnChatProcess, type SpawnChatProcess } from '../chat/chat-process.ts';
+
+export interface CliDetection {
+    installed: boolean;
+    version: string | null;
+}
+
+function definedOnly(env: Record<string, string | undefined>): Record<string, string> {
+    const defined: Record<string, string> = {};
+    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: string,
+    env: Record<string, string | undefined> = process.env,
+    spawn: SpawnChatProcess = spawnChatProcess
+): Promise<CliDetection> {
+    try {
+        let exited: (code: number | null) => void = () => undefined;
+        const code = new Promise<number | null>((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/src/providers/provider.ts

@@ -0,0 +1,46 @@
+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 {
+    // The variable the CLI reads its config folder from.
+    readonly env: string;
+    // The folder it uses without that variable, under the person's home.
+    readonly fallback: string;
+    // 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;
+}
+
+/*
+ * One agent CLI as a host knows it. Everything a provider does differently is either data on
+ * this value or behind the backend it makes, so a new CLI is a value plus a backend and nothing
+ * else changes: the session, the projector, the manager and the wire stay as they are.
+ */
+export interface ChatProvider {
+    readonly kind: AgentKind;
+    readonly name: string;
+    readonly catalog: ModelCatalog;
+    readonly capabilities: ProviderCapabilities;
+    // The executable and its leading arguments; a test points this at a fake CLI.
+    readonly command: string[];
+    // What a terminal runs to continue one of this CLI's sessions; `{id}` stands for the session id.
+    readonly resumeCommand: string;
+    /* Where this CLI keeps its login, settings and transcripts, which is what an account is. Absent on a
+       CLI with no variable to move that folder, which then only has its default account. */
+    readonly home?: ProviderHome;
+    /* The arguments for one prompt in and one answer out, no session and no chat, which is how a
+       host asks for a commit message or a title. Absent on a CLI that only runs interactively. */
+    oneShotArgs?(prompt: string): string[];
+    /* The same run with the prompt read from stdin, for a prompt too long for one argument (Linux
+       refuses one past 128 KiB) or too private for the process list. Absent on a CLI that cannot. */
+    readonly oneShotStdinArgs?: readonly string[];
+    /* The arguments that start this CLI interactively on a first prompt and then keep the session. */
+    firstPromptArgs(prompt: string): string[];
+    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;
+    createBackend(launch: BackendLaunch, host: BackendHost): ChatBackend;
+}