akm-cli 0.8.0-rc1 → 0.8.0

package/dist/integrations/agent/config.js

@@ -1,351 +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", "processes"]);
-/** Keys recognised on a profile entry. */
-const KNOWN_PROFILE_KEYS = new Set([
-    "bin",
-    "args",
-    "stdio",
-    "env",
-    "envPassthrough",
-    "timeoutMs",
-    "parseOutput",
-    "sdkMode",
-    "model",
-    "endpoint",
-    "apiKey",
-]);
 /**
- * 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;
-/** Keys recognised on a `processes[<name>]` object entry. */
-const KNOWN_PROCESS_ENTRY_KEYS = new Set(["profile", "timeoutMs"]);
-/**
- * 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;
-    }
-    if ("processes" in raw) {
-        const processes = parseProcessesMap(raw.processes);
-        if (processes)
-            out.processes = processes;
-    }
-    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;
-}
-/**
- * Parse one entry in `agent.processes`. Accepts a string (profile name) or an
- * object with optional `profile` and `timeoutMs` fields. Returns `undefined`
- * and emits a warning for entries that are neither valid strings nor valid
- * objects (warn-and-ignore).
- */
-export function parseProcessEntry(value, name) {
-    if (typeof value === "string") {
-        if (!value.trim()) {
-            warn(`[akm] Ignoring agent.processes."${name}": string value must be non-empty (a profile name).`);
-            return undefined;
-        }
-        return value.trim();
-    }
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        warn(`[akm] Ignoring agent.processes."${name}": expected a string (profile name) or an object with optional "profile" and "timeoutMs".`);
-        return undefined;
-    }
-    const raw = value;
-    // Warn on unknown keys (warn-and-ignore contract).
-    for (const key of Object.keys(raw)) {
-        if (!KNOWN_PROCESS_ENTRY_KEYS.has(key)) {
-            warn(`[akm] Ignoring unknown agent.processes."${name}" key: "${key}"`);
-        }
-    }
-    const out = {};
-    if ("profile" in raw) {
-        if (typeof raw.profile === "string" && raw.profile.trim()) {
-            out.profile = raw.profile.trim();
-        }
-        else if (raw.profile !== undefined) {
-            warn(`[akm] Ignoring agent.processes."${name}".profile: expected a non-empty string.`);
-        }
-    }
-    if ("timeoutMs" in raw) {
-        if (raw.timeoutMs === null) {
-            // null = unlimited — explicit, valid.
-            out.timeoutMs = null;
-        }
-        else 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.processes."${name}".timeoutMs: expected a positive integer (milliseconds) or null (unlimited).`);
-        }
-    }
-    return out;
-}
-/**
- * Parse the `agent.processes` map. Returns `undefined` when the value is not
- * a valid object; per-entry validation errors are warn-and-ignored (per spec §9.2).
- */
-export function parseProcessesMap(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        warn("[akm] Ignoring agent.processes: expected an object.");
-        return undefined;
-    }
-    const out = {};
-    for (const [name, raw] of Object.entries(value)) {
-        const parsed = parseProcessEntry(raw, name);
-        if (parsed !== undefined)
-            out[name] = parsed;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-/**
- * Resolve the agent profile and effective timeout for a named process.
- *
- * Resolution order:
- * 1. `config.processes[processName]` — if a string, that is the profile name;
- *    if an object, extract `profile` (and optionally `timeoutMs`).
- * 2. Profile name falls back to `config.default` when not specified in the
- *    process entry.
- * 3. `timeoutMs` falls back: `process.timeoutMs` (null = unlimited) →
- *    profile.timeoutMs → agent.timeoutMs → DEFAULT_AGENT_TIMEOUT_MS.
- *
- * Returns `{ profile, timeoutMs }` where `timeoutMs` is `undefined` when the
- * resolved timeout is `null` (unlimited) or when no timeout is set at any
- * layer (callers treat `undefined` as the DEFAULT_AGENT_TIMEOUT_MS default).
- *
- * Throws {@link ConfigError} (via {@link requireAgentProfile}) when the agent
- * block is missing or the resolved profile cannot be used.
- */
-export function resolveProcessAgentProfile(processName, agentConfig) {
-    let profileName;
-    let processTimeoutMs; // null = unlimited from config
-    const processEntry = agentConfig?.processes?.[processName];
-    if (processEntry !== undefined) {
-        if (typeof processEntry === "string") {
-            profileName = processEntry;
-        }
-        else {
-            profileName = processEntry.profile;
-            processTimeoutMs = processEntry.timeoutMs;
-        }
-    }
-    // Profile name falls back to agent.default when not set in the process entry.
-    const resolvedProfile = requireAgentProfile(agentConfig, profileName);
-    // Timeout resolution: process entry → profile → agent-level → undefined (caller applies DEFAULT).
-    let resolvedTimeoutMs;
-    if (processTimeoutMs === null) {
-        // null = explicit "unlimited" — surface as undefined so callers omit the timer.
-        resolvedTimeoutMs = undefined;
-    }
-    else if (processTimeoutMs !== undefined) {
-        resolvedTimeoutMs = processTimeoutMs;
-    }
-    else if (resolvedProfile.timeoutMs !== undefined) {
-        resolvedTimeoutMs = resolvedProfile.timeoutMs;
-    }
-    else if (agentConfig?.timeoutMs !== undefined) {
-        resolvedTimeoutMs = agentConfig.timeoutMs;
-    }
-    return { profile: resolvedProfile, timeoutMs: resolvedTimeoutMs };
-}
-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".`);
-    }
-    if (raw.sdkMode === true || raw.sdkMode === false) {
-        out.sdkMode = raw.sdkMode;
-    }
-    else if (raw.sdkMode !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".sdkMode: expected a boolean.`);
-    }
-    if (typeof raw.model === "string" && raw.model.trim()) {
-        out.model = raw.model.trim();
-    }
-    else if (raw.model !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".model: expected a non-empty string.`);
-    }
-    if (typeof raw.endpoint === "string" && raw.endpoint.trim()) {
-        out.endpoint = raw.endpoint.trim();
-    }
-    else if (raw.endpoint !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".endpoint: expected a non-empty string.`);
-    }
-    if (typeof raw.apiKey === "string" && raw.apiKey.trim()) {
-        out.apiKey = raw.apiKey.trim();
-    }
-    else if (raw.apiKey !== undefined) {
-        warn(`[akm] Ignoring agent.profiles."${name}".apiKey: expected a non-empty string.`);
-    }
-    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 && overrides?.sdkMode !== true)
+    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 ??
         {
@@ -355,110 +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,
-        sdkMode: overrides.sdkMode ?? base.sdkMode,
+        stdio: base.stdio,
+        env: base.env,
+        envPassthrough: base.envPassthrough,
+        timeoutMs: base.timeoutMs,
+        parseOutput: base.parseOutput,
+        ...(sdkMode ? { sdkMode: true } : {}),
         model: overrides.model ?? base.model,
-        endpoint: overrides.endpoint ?? base.endpoint,
-        apiKey: overrides.apiKey ?? base.apiKey,
+        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(", ")}.`);
-    }
-    // Apply the top-level agent.timeoutMs as the effective default for this
-    // profile when the profile itself has no timeout override. This makes
-    // `agent.timeoutMs` the universal fallback without requiring every
-    // profile definition in config.json to repeat it.
-    if (profile.timeoutMs === undefined && agent?.timeoutMs !== undefined) {
-        return { ...profile, timeoutMs: agent.timeoutMs };
+        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,19 +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, buildSchemaRepairPrompt, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
-export { runWithAgentRunner, selectAgentRunner } from "./runners";
+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;
+}