akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/integrations/agent/spawn.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/.
 /**
  * Agent CLI spawn wrapper (v1 spec §12.2).
  *
@@ -11,6 +14,10 @@
  * NEVER imports an LLM SDK. Agents are reachable only via shell-out;
  * this is a pre-emptive guarantee against the #222 invariant.
  */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getCommandBuilder } from "./builders";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
 /**
  * Kill the process group of `proc` with `signal`, falling back to
@@ -21,7 +28,7 @@ import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
  * reaped alongside the node wrapper. The fallback keeps test fakes working
  * without modification.
  */
-export function killGroup(proc, signal) {
+function killGroup(proc, signal) {
     if (typeof proc.pid === "number") {
         try {
             process.kill(-proc.pid, signal);
@@ -39,6 +46,60 @@ export function killGroup(proc, signal) {
     }
 }
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
+/**
+ * Supplement `existingPath` with well-known user binary directories when
+ * running in a scheduler context (cron/launchd) where PATH is stripped.
+ *
+ * Detection heuristic: if the current PATH does not contain the user's home
+ * directory, we are likely in a stripped scheduler env. In an interactive
+ * shell the user's home almost always appears (e.g. ~/.bun/bin, ~/.cargo/bin).
+ *
+ * Only directories that actually exist on disk are prepended, and only if
+ * they are not already present, so interactive-shell PATH ordering is never
+ * disturbed.
+ */
+export function supplementPathForSchedulerContext(existingPath) {
+    const home = os.homedir();
+    // If PATH already contains the home directory, we are in an interactive
+    // shell — skip supplementation entirely.
+    if (existingPath.split(path.delimiter).some((d) => d.startsWith(home))) {
+        return existingPath;
+    }
+    const candidates = pathCandidatesForCurrentPlatform(home);
+    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
+    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
+    if (toAdd.length === 0)
+        return existingPath;
+    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
+}
+function pathCandidatesForCurrentPlatform(home) {
+    if (process.platform === "win32") {
+        // Windows: Bun + Cargo + Scoop + Chocolatey + system tools. Order favors
+        // user-local installs over machine-global so the user's chosen toolchain
+        // wins. These paths are commonly stripped from Task Scheduler / service
+        // environments, mirroring the cron/launchd problem on POSIX.
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        const userProfile = process.env.USERPROFILE ?? home;
+        const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+        return [
+            path.join(userProfile, ".bun", "bin"),
+            path.join(localAppData, "Programs", "bun"),
+            path.join(userProfile, ".cargo", "bin"),
+            path.join(localAppData, "Programs", "Git", "cmd"),
+            path.join(userProfile, "scoop", "shims"),
+            path.join(programFiles, "Git", "cmd"),
+            "C:\\ProgramData\\chocolatey\\bin",
+        ];
+    }
+    return [
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".cargo", "bin"),
+        path.join(home, ".local", "bin"),
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+    ];
+}
 function resolveSpawnFn(options) {
     if (options.spawn)
         return options.spawn;
@@ -54,6 +115,10 @@ function resolveSpawnFn(options) {
  *   • Every name in `profile.envPassthrough`.
  *   • Every entry in `profile.env`.
  *   • Every entry in `options.env` (highest precedence).
+ *
+ * PATH is supplemented with well-known user binary directories when running
+ * in a scheduler context (cron/launchd) where the inherited PATH is stripped.
+ * See {@link supplementPathForSchedulerContext}.
  */
 function buildChildEnv(profile, options) {
     const source = options.envSource ?? process.env;
@@ -63,6 +128,11 @@ function buildChildEnv(profile, options) {
         if (value !== undefined)
             env[name] = value;
     }
+    // Supplement PATH after passthrough so the scheduler-context fix applies to
+    // the value actually coming from the environment source.
+    if (env.PATH !== undefined) {
+        env.PATH = supplementPathForSchedulerContext(env.PATH);
+    }
     if (profile.env) {
         for (const [k, v] of Object.entries(profile.env))
             env[k] = v;
@@ -109,19 +179,35 @@ async function readStream(stream, opts) {
  */
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
-    const timeoutMs = options.timeoutMs ?? profile.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // null = explicitly disabled (no kill timer). undefined = inherit from profile/default.
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : (profile.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
-    const args = [...profile.args, ...(options.args ?? [])];
-    if (prompt !== undefined)
-        args.push(prompt);
-    const env = buildChildEnv(profile, options);
+    // Build argv via the platform-specific builder when dispatch params are
+    // provided; fall back to the legacy positional-prompt form otherwise.
+    let builtArgv;
+    let builtEnv;
+    if (options.dispatch !== undefined) {
+        const builder = getCommandBuilder(profile.commandBuilder ?? profile.name, options.builderRegistry);
+        const built = builder.build(profile, options.dispatch);
+        builtArgv = built.argv;
+        builtEnv = built.env;
+    }
+    else {
+        const legacyArgs = [...profile.args, ...(options.args ?? [])];
+        if (prompt !== undefined)
+            legacyArgs.push(prompt);
+        builtArgv = [profile.bin, ...legacyArgs];
+    }
+    // Extra args (e.g. forwarded CLI positionals) are appended after the builder output.
+    const finalArgv = [...builtArgv, ...(options.dispatch ? (options.args ?? []) : [])];
+    const env = { ...buildChildEnv(profile, options), ...(builtEnv ?? {}) };
     const start = Date.now();
     let proc;
     try {
         const spawnFn = resolveSpawnFn(options);
-        proc = spawnFn([profile.bin, ...args], {
+        proc = spawnFn(finalArgv, {
             stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
             stdout: stdioMode === "captured" ? "pipe" : "inherit",
             stderr: stdioMode === "captured" ? "pipe" : "inherit",
@@ -153,26 +239,34 @@ export async function runAgent(profile, prompt, options = {}) {
     // BUG-M3: only flag `timedOut` when the child has not already exited. A
     // timer firing in the same microtask as `proc.exited` resolving could
     // otherwise label a clean exit as a timeout.
+    //
+    // When timeoutMs is null the kill timer is skipped entirely — the task runs
+    // until the process exits naturally. Intended for long-running local-model
+    // tasks where wall-clock time is unpredictable.
     let timedOut = false;
-    const timer = setTimeoutImpl(() => {
-        if (proc.exitCode !== null)
-            return;
-        timedOut = true;
-        killGroup(proc, "SIGTERM");
-        // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
-        setTimeoutImpl(() => {
-            if (proc.exitCode !== null)
+    let timer;
+    if (timeoutMs !== null) {
+        timer = setTimeoutImpl(() => {
+            if (!proc || proc.exitCode !== null)
                 return;
-            killGroup(proc, "SIGKILL");
-        }, 5000);
-    }, timeoutMs);
+            timedOut = true;
+            killGroup(proc, "SIGTERM");
+            // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
+            setTimeoutImpl(() => {
+                if (!proc || proc.exitCode !== null)
+                    return;
+                killGroup(proc, "SIGKILL");
+            }, 5000);
+        }, timeoutMs);
+    }
     // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
     // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
     // handler or from outside) some runtimes keep the pipe write-end open in
     // background threads, which would cause `Response.text()` to block forever.
-    // Capping stream draining at `timeoutMs + 2 000 ms` ensures the caller
-    // never hangs past the wall budget regardless of subprocess pipe behaviour.
-    const streamDrainTimeoutMs = timeoutMs + 2_000;
+    // Capping stream draining ensures the caller never hangs past the wall
+    // budget regardless of subprocess pipe behaviour.
+    // When there is no kill timer, allow up to 30 s for streams to drain.
+    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
     const stdoutPromise = stdioMode === "captured"
         ? readStream(proc.stdout ?? null, { timeoutMs: streamDrainTimeoutMs })
         : Promise.resolve("");
@@ -209,7 +303,8 @@ export async function runAgent(profile, prompt, options = {}) {
         exitCode = await proc.exited;
     }
     catch (err) {
-        clearTimeoutImpl(timer);
+        if (timer !== undefined)
+            clearTimeoutImpl(timer);
         // BUG-H2: drain stream readers before the early return so they don't
         // surface as unhandled rejections after the function resolves.
         // The streams already carry a built-in drain timeout so this allSettled
@@ -237,7 +332,7 @@ export async function runAgent(profile, prompt, options = {}) {
             stderr,
             durationMs,
             reason: "timeout",
-            error: `agent CLI "${profile.name}" timed out after ${timeoutMs}ms`,
+            error: `agent CLI "${profile.name}" timed out after ${timeoutMs ?? 0}ms`,
         };
     }
     if (exitCode !== 0) {

package/dist/integrations/github.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/.
 import * as childProcess from "node:child_process";
 export const GITHUB_API_BASE = "https://api.github.com";
 const GITHUB_TOKEN_DOMAINS = new Set(["api.github.com", "github.com", "uploads.github.com"]);

package/dist/integrations/lockfile.js

@@ -1,77 +1,46 @@
+// 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 fs from "node:fs";
 import path from "node:path";
-import { getConfigDir } from "../core/config";
+import { writeFileAtomic } from "../core/common";
+import { rethrowIfTestIsolationError } from "../core/errors";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
+import { getDataDir } from "../core/paths";
 // ── Paths ───────────────────────────────────────────────────────────────────
 const LOCKFILE_NAME = "akm.lock";
 function getLockfilePath() {
-    return path.join(getConfigDir(), LOCKFILE_NAME);
+    return path.join(getDataDir(), LOCKFILE_NAME);
 }
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
 const LOCK_RETRY_DELAY_MS = 100;
 function getLockSentinelPath() {
-    return `${getLockfilePath()}.lck`;
+    // The sentinel always lives next to the lock file it guards.
+    return `${path.join(getDataDir(), LOCKFILE_NAME)}.lck`;
 }
 async function acquireLockSentinel() {
     const sentinelPath = getLockSentinelPath();
-    // Ensure the directory exists before attempting to create the sentinel
+    // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
-        try {
-            fs.writeFileSync(sentinelPath, String(process.pid), { flag: "wx" });
-            return true; // Sentinel created — we own the lock
+        if (tryAcquireLockSync(sentinelPath, String(process.pid))) {
+            return true; // Sentinel created — we own the lock.
         }
-        catch (err) {
-            if (err.code !== "EEXIST")
-                throw err;
-            // Check for stale lock — if the owning PID is no longer running, reclaim it
-            if (tryReclaimStaleSentinel(sentinelPath)) {
-                continue; // Sentinel removed — retry immediately
-            }
-            // Another process holds the lock — wait briefly before retrying
-            if (attempt < LOCK_MAX_RETRIES - 1) {
-                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
-            }
+        if (probeLock(sentinelPath).state === "stale") {
+            releaseLock(sentinelPath);
+            continue; // Reclaimed — retry immediately.
         }
-    }
-    // Best-effort: proceed without the lock rather than failing the install
-    return false;
-}
-/**
- * Check if the sentinel was left by a dead process and remove it if so.
- * Returns true if the sentinel was reclaimed (removed).
- */
-function tryReclaimStaleSentinel(sentinelPath) {
-    try {
-        const content = fs.readFileSync(sentinelPath, "utf8").trim();
-        const pid = parseInt(content, 10);
-        if (Number.isNaN(pid) || pid <= 0) {
-            // Invalid PID in sentinel — reclaim it
-            fs.unlinkSync(sentinelPath);
-            return true;
-        }
-        // Check if the process is still alive (signal 0 doesn't kill, just checks)
-        try {
-            process.kill(pid, 0);
-            return false; // Process is alive — lock is valid
+        // Another process holds the lock — wait briefly before retrying.
+        if (attempt < LOCK_MAX_RETRIES - 1) {
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
         }
-        catch {
-            // Process is dead — reclaim the stale lock
-            fs.unlinkSync(sentinelPath);
-            return true;
-        }
-    }
-    catch {
-        return false; // Can't read or remove — leave it alone
     }
+    // Best-effort: proceed without the lock rather than failing the install.
+    return false;
 }
 function releaseLockSentinel() {
-    try {
-        fs.unlinkSync(getLockSentinelPath());
-    }
-    catch {
-        /* ignore — sentinel may already be gone */
-    }
+    releaseLock(getLockSentinelPath());
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -82,28 +51,20 @@ export function readLockfile() {
             return [];
         return raw.filter(isValidLockfileEntry);
     }
-    catch {
+    catch (err) {
+        // Defense-in-depth: getLockfilePath() is outside this try block, but a
+        // future refactor that pushes a getDataDir() call inside must not mask
+        // the bun-test isolation guard as "empty lockfile".
+        rethrowIfTestIsolationError(err);
         return [];
     }
 }
 export function writeLockfile(entries) {
-    const lockfilePath = getLockfilePath();
+    // Always write to $DATA — never to the legacy $CONFIG location.
+    const lockfilePath = path.join(getDataDir(), LOCKFILE_NAME);
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
-    const tmpPath = `${lockfilePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
-    try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(entries, null, 2)}\n`, "utf8");
-        fs.renameSync(tmpPath, lockfilePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeFileAtomic(lockfilePath, `${JSON.stringify(entries, null, 2)}\n`);
 }
 export async function upsertLockEntry(entry) {
     const acquired = await acquireLockSentinel();
@@ -118,6 +79,8 @@ export async function upsertLockEntry(entry) {
     }
 }
 export async function removeLockEntry(id) {
+    if (!fs.existsSync(getDataDir()))
+        return;
     const acquired = await acquireLockSentinel();
     try {
         const entries = readLockfile();

package/dist/integrations/session-logs/index.js

@@ -0,0 +1,68 @@
+// 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 { ClaudeCodeProvider } from "./providers/claude-code";
+import { OpenCodeProvider } from "./providers/opencode";
+const HARNESSES = [new ClaudeCodeProvider(), new OpenCodeProvider()];
+const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENOENT|timeout/i;
+/**
+ * Returns all available session log harnesses for the current machine.
+ * Add new harnesses to HARNESSES to support additional agent runtimes.
+ */
+export function getAvailableHarnesses() {
+    return HARNESSES.filter((harness) => harness.isAvailable());
+}
+export function normalizeSessionTopic(text) {
+    const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
+    if (normalized.length < 10)
+        return undefined;
+    return normalized.slice(0, 60);
+}
+export function aggregateSessionEvents(events) {
+    const counts = new Map();
+    for (const event of events) {
+        const topic = normalizeSessionTopic(event.text);
+        if (!topic)
+            continue;
+        const isFailurePattern = ERROR_PATTERNS.test(topic);
+        if (!isFailurePattern)
+            continue;
+        const existing = counts.get(topic) ?? {
+            count: 0,
+            isFailurePattern,
+            sources: new Set(),
+            topic,
+        };
+        existing.count += 1;
+        existing.isFailurePattern = existing.isFailurePattern || isFailurePattern;
+        existing.sources.add(event.harness);
+        counts.set(topic, existing);
+    }
+    return [...counts.values()]
+        .filter((entry) => entry.count >= 2)
+        .sort((a, b) => b.count - a.count || a.topic.localeCompare(b.topic))
+        .slice(0, 15)
+        .map((entry) => ({
+        topic: entry.topic,
+        frequency: entry.count,
+        source: [...entry.sources].sort().join(","),
+        isFailurePattern: entry.isFailurePattern,
+    }));
+}
+/**
+ * Scan recent session logs from all available harnesses and return
+ * repeated failure patterns that might warrant new AKM assets.
+ */
+export function getExecutionLogCandidates(sinceDays = 7) {
+    const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
+    const events = [];
+    for (const harness of getAvailableHarnesses()) {
+        try {
+            events.push(...harness.readEvents({ sinceMs }));
+        }
+        catch {
+            // individual harness failures are non-fatal
+        }
+    }
+    return aggregateSessionEvents(events);
+}

package/dist/integrations/session-logs/providers/claude-code.js

@@ -0,0 +1,59 @@
+// 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 fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+export class ClaudeCodeProvider {
+    name = "claude-code";
+    isAvailable() {
+        return fs.existsSync(CLAUDE_PROJECTS_DIR);
+    }
+    *readEvents(input) {
+        try {
+            for (const jsonlPath of this.#walkJsonl(CLAUDE_PROJECTS_DIR)) {
+                const stat = fs.statSync(jsonlPath);
+                if (stat.mtimeMs < input.sinceMs)
+                    continue;
+                const lines = fs.readFileSync(jsonlPath, "utf8").split("\n").filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        const entry = JSON.parse(line);
+                        const text = entry?.message?.content ?? entry?.content ?? "";
+                        if (typeof text !== "string" || text.length < 10)
+                            continue;
+                        yield {
+                            harness: this.name,
+                            text,
+                            ts: typeof entry?.timestamp === "number" ? entry.timestamp : stat.mtimeMs,
+                            sessionId: typeof entry?.session_id === "string" ? entry.session_id : undefined,
+                            role: typeof entry?.role === "string" ? entry.role : "unknown",
+                            filePath: jsonlPath,
+                        };
+                    }
+                    catch {
+                        // skip malformed lines
+                    }
+                }
+            }
+        }
+        catch {
+            return;
+        }
+    }
+    *#walkJsonl(dir) {
+        try {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    yield* this.#walkJsonl(full);
+                else if (entry.name.endsWith(".jsonl"))
+                    yield full;
+            }
+        }
+        catch {
+            // permission errors etc.
+        }
+    }
+}

package/dist/integrations/session-logs/providers/opencode.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/.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function getOpenCodeLogDir() {
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "opencode");
+    }
+    return path.join(os.homedir(), ".local", "share", "opencode");
+}
+export class OpenCodeProvider {
+    name = "opencode";
+    #logDir = getOpenCodeLogDir();
+    isAvailable() {
+        return fs.existsSync(this.#logDir);
+    }
+    *readEvents(input) {
+        try {
+            for (const file of fs.readdirSync(this.#logDir)) {
+                const full = path.join(this.#logDir, file);
+                const stat = fs.statSync(full);
+                if (stat.mtimeMs < input.sinceMs)
+                    continue;
+                if (!file.endsWith(".json") && !file.endsWith(".jsonl") && !file.endsWith(".log"))
+                    continue;
+                const content = fs.readFileSync(full, "utf8");
+                const lines = content.includes("\n") ? content.split("\n") : [content];
+                for (const line of lines) {
+                    try {
+                        const entry = JSON.parse(line);
+                        const text = entry?.content ?? entry?.message ?? entry?.text ?? "";
+                        if (typeof text !== "string" || text.length < 10)
+                            continue;
+                        yield {
+                            harness: this.name,
+                            text,
+                            ts: typeof entry?.timestamp === "number" ? entry.timestamp : stat.mtimeMs,
+                            sessionId: typeof entry?.sessionId === "string" ? entry.sessionId : undefined,
+                            role: typeof entry?.role === "string" ? entry.role : "unknown",
+                            filePath: full,
+                        };
+                    }
+                    catch {
+                        // skip malformed
+                    }
+                }
+            }
+        }
+        catch {
+            return;
+        }
+    }
+}

package/dist/integrations/session-logs/types.js

@@ -0,0 +1,4 @@
+// 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 {};

package/dist/llm/call-ai.js

@@ -0,0 +1,62 @@
+// 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 { getDefaultLlmConfig } from "../core/config";
+import { warn } from "../core/warn";
+import { resolveAgentProfile, runAgent } from "../integrations/agent";
+import { chatCompletion } from "./client";
+/**
+ * Unified AI call: prefers the default agent profile, falls back to the
+ * default LLM profile. When neither is configured, returns a structured
+ * error pointing the user at `akm setup`.
+ */
+export async function callAi(config, prompt, opts = {}) {
+    const defaultAgentName = config.defaults?.agent;
+    if (defaultAgentName) {
+        try {
+            const profile = resolveAgentProfile(defaultAgentName, config.profiles?.agent?.[defaultAgentName]);
+            if (!profile) {
+                return {
+                    ok: false,
+                    error: `Agent profile "${defaultAgentName}" is not built-in and has no \`bin\` override.`,
+                };
+            }
+            const result = await runAgent(profile, prompt, {
+                stdio: opts.draftFilePath ? "interactive" : "captured",
+                parseOutput: "text",
+                timeoutMs: opts.timeoutMs,
+            });
+            if (!result.ok)
+                return { ok: false, error: result.error ?? result.reason ?? "agent failed" };
+            return { ok: true, content: result.stdout ?? "", path: "agent-cli" };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+    }
+    const llmConfig = getDefaultLlmConfig(config);
+    if (llmConfig) {
+        if (opts.draftFilePath) {
+            warn("[akm] No agent CLI configured — falling back to LLM API. " +
+                "File-write contract unavailable; expecting JSON in stdout. " +
+                "Install an agent CLI and run `akm setup` for full functionality.");
+        }
+        const messages = [];
+        if (opts.systemPrompt)
+            messages.push({ role: "system", content: opts.systemPrompt });
+        messages.push({ role: "user", content: prompt });
+        try {
+            const content = await chatCompletion(llmConfig, messages, {
+                ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+            });
+            return { ok: true, content, path: "llm-http" };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+    }
+    return {
+        ok: false,
+        error: "No AI connection configured. Run `akm setup` or set `defaults.agent`/`defaults.llm`.",
+    };
+}