akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/integrations/agent/config.js

@@ -1,190 +1,25 @@
-/**
- * Parser + resolver for the optional `agent` config block (v1 spec §12).
- *
- * The on-disk shape is:
- *
- * ```jsonc
- * {
- *   "agent": {
- *     "default": "opencode",
- *     "timeoutMs": 60000,
- *     "profiles": {
- *       "opencode": { "bin": "opencode", "args": ["--non-interactive"], ... }
- *     }
- *   }
- * }
- * ```
- *
- * Unknown keys at any level under `agent` are warn-and-ignored — this is the
- * v1 §9.2 contract. Missing `agent` block disables agent commands; callers
- * should reach for {@link requireAgentConfig} to surface a stable
- * `ConfigError` with a hint pointing at setup.
- *
- * No LLM SDK is imported here. The runtime path is shell-out only (see
- * `./spawn.ts`).
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { ConfigError } from "../../core/errors";
 import { warn } from "../../core/warn";
 import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-/** Keys recognised at the top level of an `agent` config block. */
-const KNOWN_AGENT_KEYS = new Set(["default", "timeoutMs", "profiles"]);
-/** Keys recognised on a profile entry. */
-const KNOWN_PROFILE_KEYS = new Set(["bin", "args", "stdio", "env", "envPassthrough", "timeoutMs", "parseOutput"]);
 /**
- * Default hard timeout for an agent CLI. Spec §12.2 calls for a hard
- * timeout; 60s matches the example value in `docs/configuration.md`.
+ * Default hard timeout for an agent CLI (60s — matches the value used in
+ * `docs/configuration.md`).
  */
 export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
 /**
- * Parse a raw value (typically `rawConfig.agent` from `JSON.parse`) into a
- * normalised {@link AgentConfig}. Returns `undefined` when the value is not
- * an object (i.e. the block is absent or malformed at the root level — for
- * malformed roots we emit a warning).
- *
- * Unknown keys (top-level and per-profile) are warn-and-ignore. Type errors
- * on individual fields are warn-and-ignore so a bad `timeoutMs` does not
- * break the rest of the block.
- */
-export function parseAgentConfig(value) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        warn('[akm] Ignoring "agent" config: expected an object.');
-        return undefined;
-    }
-    const raw = value;
-    const out = {};
-    for (const key of Object.keys(raw)) {
-        if (!KNOWN_AGENT_KEYS.has(key)) {
-            warn(`[akm] Ignoring unknown agent config key: "${key}"`);
-        }
-    }
-    if ("default" in raw) {
-        if (typeof raw.default === "string" && raw.default.trim()) {
-            out.default = raw.default.trim();
-        }
-        else if (raw.default !== undefined) {
-            warn("[akm] Ignoring agent.default: expected a non-empty string.");
-        }
-    }
-    if ("timeoutMs" in raw) {
-        if (typeof raw.timeoutMs === "number" &&
-            Number.isFinite(raw.timeoutMs) &&
-            Number.isInteger(raw.timeoutMs) &&
-            raw.timeoutMs > 0) {
-            out.timeoutMs = raw.timeoutMs;
-        }
-        else {
-            warn("[akm] Ignoring agent.timeoutMs: expected a positive integer (milliseconds).");
-        }
-    }
-    if ("profiles" in raw) {
-        const profiles = parseAgentProfilesMap(raw.profiles);
-        if (profiles)
-            out.profiles = profiles;
-    }
-    return out;
-}
-function parseAgentProfilesMap(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        warn("[akm] Ignoring agent.profiles: expected an object.");
-        return undefined;
-    }
-    const out = {};
-    for (const [name, raw] of Object.entries(value)) {
-        const parsed = parseAgentProfileConfig(name, raw);
-        if (parsed)
-            out[name] = parsed;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-function parseAgentProfileConfig(name, value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        warn(`[akm] Ignoring agent.profiles."${name}": expected an object.`);
-        return undefined;
-    }
-    const raw = value;
-    const out = {};
-    for (const key of Object.keys(raw)) {
-        if (!KNOWN_PROFILE_KEYS.has(key)) {
-            warn(`[akm] Ignoring unknown agent.profiles."${name}" key: "${key}"`);
-        }
-    }
-    if (typeof raw.bin === "string" && raw.bin.trim()) {
-        out.bin = raw.bin.trim();
-    }
-    else if (raw.bin !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".bin: expected a non-empty string.`);
-    }
-    if (Array.isArray(raw.args)) {
-        const args = raw.args.filter((a) => typeof a === "string");
-        if (args.length === raw.args.length) {
-            out.args = args;
-        }
-        else {
-            warn(`[akm] Ignoring non-string entries in agent.profiles."${name}".args.`);
-            if (args.length > 0)
-                out.args = args;
-        }
-    }
-    else if (raw.args !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".args: expected an array of strings.`);
-    }
-    if (raw.stdio === "captured" || raw.stdio === "interactive") {
-        out.stdio = raw.stdio;
-    }
-    else if (raw.stdio !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".stdio: expected "captured" or "interactive".`);
-    }
-    if (typeof raw.env === "object" && raw.env !== null && !Array.isArray(raw.env)) {
-        const env = {};
-        for (const [k, v] of Object.entries(raw.env)) {
-            if (typeof v === "string")
-                env[k] = v;
-        }
-        if (Object.keys(env).length > 0)
-            out.env = env;
-    }
-    else if (raw.env !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".env: expected a string-valued object.`);
-    }
-    if (Array.isArray(raw.envPassthrough)) {
-        const list = raw.envPassthrough.filter((s) => typeof s === "string" && s.length > 0);
-        if (list.length > 0)
-            out.envPassthrough = list;
-    }
-    else if (raw.envPassthrough !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".envPassthrough: expected an array of strings.`);
-    }
-    if (typeof raw.timeoutMs === "number" &&
-        Number.isFinite(raw.timeoutMs) &&
-        Number.isInteger(raw.timeoutMs) &&
-        raw.timeoutMs > 0) {
-        out.timeoutMs = raw.timeoutMs;
-    }
-    else if (raw.timeoutMs !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".timeoutMs: expected a positive integer.`);
-    }
-    if (raw.parseOutput === "text" || raw.parseOutput === "json") {
-        out.parseOutput = raw.parseOutput;
-    }
-    else if (raw.parseOutput !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".parseOutput: expected "text" or "json".`);
-    }
-    return out;
-}
-/**
- * Merge a user override (from `agent.profiles[<name>]`) on top of the
- * built-in profile (if any) and return the resolved profile. If `name`
- * matches no built-in and the user override has no `bin`, returns
- * `undefined` — the profile is unusable.
- *
- * Used at the spawn site, never at config-load time. Keeping merge logic
- * here means the parser stays a pure shape-checker.
+ * Resolve the effective `AgentProfile` for `name` by merging the optional
+ * user override (`profiles.agent[name]`) on top of the built-in profile (if
+ * any). Returns `undefined` when neither yields a usable profile.
  */
 export function resolveAgentProfile(name, overrides) {
     const builtin = getBuiltinAgentProfile(name);
-    if (!builtin && !overrides?.bin)
+    const platform = overrides?.platform;
+    // For opencode-sdk profiles, allow synthesizing without a built-in.
+    const sdkMode = platform === "opencode-sdk";
+    if (!builtin && !overrides?.bin && !sdkMode)
         return undefined;
     const base = builtin ??
         {
@@ -194,99 +29,156 @@ export function resolveAgentProfile(name, overrides) {
             stdio: "captured",
             envPassthrough: [],
             parseOutput: "text",
+            ...(sdkMode ? { sdkMode: true } : {}),
         };
     if (!overrides)
         return base;
-    const merged = {
+    return {
         name,
         bin: overrides.bin ?? base.bin,
         args: overrides.args ?? base.args,
-        stdio: overrides.stdio ?? base.stdio,
-        env: overrides.env ?? base.env,
-        envPassthrough: overrides.envPassthrough
-            ? mergePassthrough(base.envPassthrough, overrides.envPassthrough)
-            : base.envPassthrough,
-        timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
-        parseOutput: overrides.parseOutput ?? base.parseOutput,
+        stdio: base.stdio,
+        env: base.env,
+        envPassthrough: base.envPassthrough,
+        timeoutMs: base.timeoutMs,
+        parseOutput: base.parseOutput,
+        ...(sdkMode ? { sdkMode: true } : {}),
+        model: overrides.model ?? base.model,
+        endpoint: base.endpoint,
+        apiKey: base.apiKey,
+        commandBuilder: base.commandBuilder,
+        modelAliases: base.modelAliases,
     };
-    return merged;
-}
-function mergePassthrough(base, extra) {
-    const seen = new Set();
-    const out = [];
-    for (const k of [...base, ...extra]) {
-        if (!seen.has(k)) {
-            seen.add(k);
-            out.push(k);
-        }
-    }
-    return out;
 }
 /**
  * Resolve the runnable profile for `name`, or `undefined` if none is
- * available (no built-in and no user override with a `bin`).
+ * available (no built-in and no user override).
  */
-export function resolveProfileFromConfig(name, agent) {
-    return resolveAgentProfile(name, agent?.profiles?.[name]);
+export function resolveProfileFromConfig(name, config) {
+    return resolveAgentProfile(name, config?.profiles?.agent?.[name]);
 }
 /**
- * Return the names of every profile available in `agent` config (built-in
- * names plus any user-defined ones). Sorted, deduplicated.
+ * Return the names of every agent profile available in `config` — built-ins
+ * plus any user-defined entries under `profiles.agent`. Sorted, deduplicated.
  */
-export function listAgentProfileNames(agent) {
+export function listAgentProfileNames(config) {
     const seen = new Set(BUILTIN_AGENT_PROFILE_NAMES);
-    for (const name of Object.keys(agent?.profiles ?? {}))
+    for (const name of Object.keys(config?.profiles?.agent ?? {}))
         seen.add(name);
     return [...seen].sort();
 }
 /**
- * Resolve the default profile name. Order: explicit `name` arg → config
- * `agent.default` → undefined.
+ * Resolve the default agent profile name. Order: explicit `requested` arg →
+ * `config.defaults.agent` → undefined.
  */
-export function resolveDefaultProfileName(agent, requested) {
+export function resolveDefaultProfileName(config, requested) {
     if (requested?.trim())
         return requested.trim();
-    if (agent?.default?.trim())
-        return agent.default.trim();
+    const def = config?.defaults?.agent;
+    if (typeof def === "string" && def.trim())
+        return def.trim();
     return undefined;
 }
 /**
- * Throw a {@link ConfigError} with a stable hint when the caller needs
- * `agent` config but it is missing or unresolvable.
- *
- * Covers two cases per acceptance criteria:
- *
- * 1. The `agent` block is absent — agent commands are disabled.
- * 2. The block exists but no usable profile (no `default`, no requested
- *    name, or the named profile cannot be resolved).
- *
- * Use as `const profile = requireAgentProfile(config.agent, requestedName)`.
+ * Throw a stable `ConfigError` when the caller needs an agent profile but
+ * none can be resolved.
  */
-export function requireAgentProfile(agent, requested) {
-    if (!agent) {
-        throw new ConfigError("agent commands are disabled: no `agent` block in config.json.", "INVALID_CONFIG_FILE", 'Run `akm setup` to detect and configure an agent CLI, or add an `agent` block manually (see docs/configuration.md "agent.*").');
+export function requireAgentProfile(config, requested) {
+    if (!config) {
+        throw new ConfigError("agent commands are disabled: no agent configuration in config.json.", "INVALID_CONFIG_FILE", "Run `akm setup` to detect and configure an agent CLI, or add an entry under `profiles.agent` and set `defaults.agent`.");
     }
-    const name = resolveDefaultProfileName(agent, requested);
+    const name = resolveDefaultProfileName(config, requested);
     if (!name) {
-        throw new ConfigError("agent commands require a profile: pass --profile or set `agent.default` in config.json.", "INVALID_CONFIG_FILE", `Available profiles: ${listAgentProfileNames(agent).join(", ")}.`);
+        throw new ConfigError("agent commands require a profile: pass --profile or set `defaults.agent` in config.json.", "INVALID_CONFIG_FILE", `Available profiles: ${listAgentProfileNames(config).join(", ")}.`);
     }
-    const profile = resolveProfileFromConfig(name, agent);
+    const profile = resolveProfileFromConfig(name, config);
     if (!profile) {
-        throw new ConfigError(`agent profile "${name}" is not built-in and has no \`bin\` override.`, "INVALID_CONFIG_FILE", `Define agent.profiles."${name}".bin in config.json, or pick one of: ${listAgentProfileNames(agent).join(", ")}.`);
+        throw new ConfigError(`agent profile "${name}" is not built-in and has no \`bin\` override.`, "INVALID_CONFIG_FILE", `Define profiles.agent."${name}".bin in config.json, or pick one of: ${listAgentProfileNames(config).join(", ")}.`);
     }
     return profile;
 }
+/**
+ * Resolve the agent profile bound to a named improve process. Reads from
+ * `profiles.improve.default.processes.<processName>` for the profile binding,
+ * then falls back to `defaults.agent`.
+ */
+export function resolveProcessAgentProfile(processName, config) {
+    const processEntry = config?.profiles?.improve?.default?.processes;
+    const entry = processEntry?.[processName];
+    const profileName = entry?.profile;
+    const profile = requireAgentProfile(config, profileName);
+    let resolvedTimeoutMs;
+    if (entry?.timeoutMs === null) {
+        resolvedTimeoutMs = null;
+    }
+    else if (typeof entry?.timeoutMs === "number") {
+        resolvedTimeoutMs = entry.timeoutMs;
+    }
+    else if (profile.timeoutMs !== undefined) {
+        resolvedTimeoutMs = profile.timeoutMs;
+    }
+    return { profile, timeoutMs: resolvedTimeoutMs };
+}
 /**
  * Convenience: list every fully-resolved profile (built-ins merged with
- * any user overrides). Used by setup detection to enumerate candidates.
+ * user overrides). Used by setup detection to enumerate candidates.
  */
-export function listResolvedAgentProfiles(agent) {
+export function listResolvedAgentProfiles(config) {
     const resolved = [];
     const builtins = listBuiltinAgentProfiles();
-    for (const name of listAgentProfileNames(agent)) {
-        const profile = resolveProfileFromConfig(name, agent) ?? builtins[name];
+    for (const name of listAgentProfileNames(config)) {
+        const profile = resolveProfileFromConfig(name, config) ?? builtins[name];
         if (profile)
             resolved.push(profile);
     }
     return resolved;
 }
+/**
+ * Parse the v2 `profiles.agent` map (AgentProfileConfigV2 shape with required
+ * `platform` field). Returns a map of profile name → AgentProfileConfigV2.
+ */
+export function parseAgentProfilesMapV2(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const out = {};
+    const VALID_PLATFORMS = ["opencode", "claude", "opencode-sdk"];
+    for (const [name, raw] of Object.entries(value)) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            warn(`[akm] Ignoring profiles.agent["${name}"]: expected an object.`);
+            continue;
+        }
+        const obj = raw;
+        if (!VALID_PLATFORMS.includes(obj.platform)) {
+            warn(`[akm] Ignoring profiles.agent["${name}"]: missing or invalid "platform" (must be one of: ${VALID_PLATFORMS.join(", ")}).`);
+            continue;
+        }
+        const profile = {
+            platform: obj.platform,
+        };
+        if (typeof obj.bin === "string" && obj.bin.trim())
+            profile.bin = obj.bin.trim();
+        if (Array.isArray(obj.args) && obj.args.every((a) => typeof a === "string")) {
+            profile.args = obj.args;
+        }
+        if (typeof obj.workspace === "string" && obj.workspace.trim())
+            profile.workspace = obj.workspace.trim();
+        if (typeof obj.model === "string" && obj.model.trim())
+            profile.model = obj.model.trim();
+        out[name] = profile;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Stub kept for source-compat with callers that previously used the v1 agent
+ * config parser. After 0.8.0 there is no separate `agent` block to parse — the
+ * loaded `AkmConfig` already carries the agent data on `profiles.agent` and
+ * `defaults.agent`. This function is a no-op alias for those callers.
+ *
+ * @deprecated v0.8.0 — the unified `AkmConfig` IS the agent config. Use the
+ * profile/defaults accessors above instead.
+ */
+export function parseAgentConfig(_value) {
+    // No-op: there is no separate agent block in 0.8.0. Callers should pass
+    // their loaded `AkmConfig` directly to `requireAgentProfile` etc.
+    return undefined;
+}

package/dist/integrations/agent/detect.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Setup-time agent CLI detection (v1 spec §12.3).
  *

package/dist/integrations/agent/index.js

@@ -1,17 +1,11 @@
-/**
- * Internal entry point for the `agent` integration. CLI-only project — no
- * public exports map. Other akm modules import from this barrel for the
- * sake of grouping imports.
- *
- * Surface:
- *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
- *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
- *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
- *   • Spawn: runAgent.
- *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+export { getCommandBuilder } from "./builders";
 export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
 export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
+export { listBuiltinModelAliases, resolveModel } from "./model-aliases";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-export { buildProposePrompt, buildReflectPrompt, parseAgentProposalPayload, stripJsonFences } from "./prompts";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
+export { runAgentSdk } from "./sdk-runner";
 export { runAgent } from "./spawn";

package/dist/integrations/agent/model-aliases.js

@@ -0,0 +1,55 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Built-in alias table. Alias keys are lowercase.
+ *
+ * Platform model string conventions:
+ *   opencode — "<provider>/<model>"  e.g. "opencode/claude-opus-4-7"
+ *   claude   — bare model name       e.g. "claude-opus-4-7"
+ *              (Claude Code also accepts its own built-in shorthands, but we
+ *               always resolve to the full name for determinism)
+ */
+const BUILTIN_ALIASES = [
+    {
+        alias: "opus",
+        platforms: {
+            claude: "claude-opus-4-7",
+            opencode: "opencode/claude-opus-4-7",
+        },
+    },
+    {
+        alias: "sonnet",
+        platforms: {
+            claude: "claude-sonnet-4-6",
+            opencode: "opencode/claude-sonnet-4-6",
+        },
+    },
+    {
+        alias: "haiku",
+        platforms: {
+            claude: "claude-haiku-4-5-20251001",
+            opencode: "opencode/claude-haiku-4-5",
+        },
+    },
+];
+/**
+ * Resolve a model alias or exact model ID to the string the target platform
+ * CLI expects for its --model flag.
+ *
+ * @param model   Raw alias ("opus") or exact model ID ("claude-opus-4-7").
+ * @param platform Builder platform name ("claude", "opencode", ...).
+ * @param custom  Profile-level aliases from config.json — take priority over builtins.
+ * @returns Resolved model string, or `model` verbatim when no alias matches.
+ */
+export function resolveModel(model, platform, custom) {
+    const key = model.toLowerCase();
+    if (custom?.[key])
+        return custom[key];
+    const entry = BUILTIN_ALIASES.find((a) => a.alias === key);
+    return entry?.platforms[platform] ?? model;
+}
+/** Return all built-in alias entries (for tests and documentation). */
+export function listBuiltinModelAliases() {
+    return BUILTIN_ALIASES;
+}

package/dist/integrations/agent/profiles.js

@@ -1,8 +1,13 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR"];
 /**
  * Built-in profiles for the five agent CLIs the v1 spec calls out
  * explicitly. The fields here are conservative defaults — every value is
  * overridable from user config.
+ *
+ * For headless/automation use (propose, reflect, tasks), use the '-headless' variant.
  */
 const BUILTINS = {
     opencode: {
@@ -46,15 +51,75 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
-/** Names of every built-in profile. Stable, sorted. */
+/**
+ * Headless variants of the five base profiles for automation use (propose, reflect, tasks).
+ *
+ * These profiles use `stdio: "captured"` and `parseOutput: "json"` so the
+ * agent's response can be read from stdout. They share the same `bin` and
+ * `envPassthrough` as the corresponding base profile but are intentionally
+ * kept out of `BUILTIN_AGENT_PROFILE_NAMES` (and therefore out of CLI
+ * detection/enumeration) to avoid showing up as separate installable profiles.
+ *
+ * Users may reference them by name via `--profile opencode-headless` or by
+ * setting `agent.default: "opencode-headless"` in config.json.
+ */
+const HEADLESS_BUILTINS = {
+    "opencode-headless": {
+        name: "opencode-headless",
+        bin: "opencode",
+        args: ["run"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
+        parseOutput: "json",
+    },
+    "claude-headless": {
+        name: "claude-headless",
+        bin: "claude",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "ANTHROPIC_API_KEY", "CLAUDE_CONFIG"],
+        parseOutput: "json",
+    },
+    "codex-headless": {
+        name: "codex-headless",
+        bin: "codex",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "CODEX_CONFIG"],
+        parseOutput: "json",
+    },
+    "gemini-headless": {
+        name: "gemini-headless",
+        bin: "gemini",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GEMINI_API_KEY", "GOOGLE_API_KEY"],
+        parseOutput: "json",
+    },
+    "aider-headless": {
+        name: "aider-headless",
+        bin: "aider",
+        args: ["--no-auto-commits"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+        parseOutput: "json",
+    },
+};
+/**
+ * Names of the five primary built-in profiles. Stable, sorted. Does NOT
+ * include the `-headless` variants (those are resolvable by name but are
+ * excluded from detection/enumeration flows).
+ */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
-/** Returns the built-in profile by name, or `undefined` if not built-in. */
+/** Returns the built-in profile by name (including headless variants), or `undefined` if not found. */
 export function getBuiltinAgentProfile(name) {
-    return BUILTINS[name];
+    return BUILTINS[name] ?? HEADLESS_BUILTINS[name];
 }
 /**
- * Return a deep copy of every built-in profile keyed by name. Callers
- * should not assume reference equality with subsequent calls.
+ * Return a deep copy of every primary built-in profile keyed by name.
+ * Headless variants are NOT included — use `getBuiltinAgentProfile(name)`
+ * to look them up by name. Callers should not assume reference equality with
+ * subsequent calls.
  */
 export function listBuiltinAgentProfiles() {
     const out = {};