akm-cli 0.7.5 → 0.8.0-rc.3

package/dist/integrations/agent/sdk-runner.js

@@ -0,0 +1,120 @@
+/**
+ * OpenCode SDK agent runner — uses embedded @opencode-ai/sdk instead of
+ * Bun.spawn. Requires no agent CLI binary to be installed. The user provides
+ * an OpenAI-compatible endpoint (or inherits from config.llm) for the SDK.
+ */
+// Singleton server — started once per process, reused across calls
+let _server = null;
+/**
+ * Close the singleton OpenCode SDK server and reset the handle.
+ * Primarily for use in tests to ensure clean teardown between test runs.
+ */
+export function closeServer() {
+    try {
+        _server?.server.close();
+    }
+    catch {
+        /* ignore */
+    }
+    _server = null;
+}
+async function getOrStartServer(profile, llmConfig) {
+    if (_server)
+        return _server;
+    const { createOpencode } = await import("@opencode-ai/sdk").catch(() => {
+        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
+    });
+    // Resolve endpoint and model: profile fields take precedence over config.llm
+    const endpoint = profile.endpoint ?? llmConfig?.endpoint;
+    const apiKey = profile.apiKey ?? llmConfig?.apiKey;
+    const model = profile.model;
+    const sdkConfig = {};
+    if (model)
+        sdkConfig.model = model;
+    if (endpoint || apiKey) {
+        // Configure a custom OpenAI-compatible provider
+        sdkConfig.provider = {
+            "akm-custom": {
+                npm: "@ai-sdk/openai-compatible",
+                options: {
+                    baseURL: endpoint?.replace(/\/chat\/completions$/, "").replace(/\/$/, ""),
+                    ...(apiKey ? { apiKey } : {}),
+                },
+            },
+        };
+        // Use the custom provider's model if not already qualified
+        if (model && !model.includes("/")) {
+            sdkConfig.model = `akm-custom/${model}`;
+        }
+    }
+    _server = (await createOpencode(Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {}));
+    process.once("exit", () => {
+        closeServer();
+    });
+    if (!_server)
+        throw new Error("Failed to initialise OpenCode SDK server.");
+    return _server;
+}
+export async function runAgentSdk(profile, prompt, _opts = {}, llmConfig) {
+    const start = Date.now();
+    let client;
+    try {
+        ({ client } = await getOrStartServer(profile, llmConfig));
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: String(e),
+        };
+    }
+    // One session per call — do NOT reuse (history accumulates, token costs grow)
+    const sessionRes = await client.session.create({ body: { title: "akm" } });
+    const sessionId = sessionRes.data?.id;
+    if (!sessionId) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "Failed to create session",
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: "Failed to create OpenCode session",
+        };
+    }
+    try {
+        const result = await client.session.prompt({
+            path: { id: sessionId },
+            body: { parts: [{ type: "text", text: prompt }] },
+        });
+        const parts = result.data?.parts ?? [];
+        const textPart = parts.find((p) => p.type === "text");
+        const stdout = textPart?.text ?? "";
+        return {
+            ok: true,
+            stdout,
+            stderr: "",
+            durationMs: Date.now() - start,
+            exitCode: 0,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "non_zero_exit",
+            error: String(e),
+        };
+    }
+    finally {
+        // Clean up session to prevent disk accumulation in ~/.local/share/opencode/
+        await client.session.delete({ path: { id: sessionId } }).catch(() => { });
+    }
+}

package/dist/integrations/agent/spawn.js

@@ -11,6 +11,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 +25,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 +43,39 @@ 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 = [
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".cargo", "bin"),
+        path.join(home, ".local", "bin"),
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+    ];
+    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 resolveSpawnFn(options) {
     if (options.spawn)
         return options.spawn;
@@ -54,6 +91,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 +104,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 +155,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 +215,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(() => {
+    let timer;
+    if (timeoutMs !== null) {
+        timer = setTimeoutImpl(() => {
             if (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.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 +279,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 +308,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/lockfile.js

@@ -1,16 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
-import { getConfigDir } from "../core/config";
+import { writeFileAtomic } from "../core/common";
+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();
@@ -87,23 +89,11 @@ export function readLockfile() {
     }
 }
 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 +108,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,65 @@
+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,56 @@
+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,52 @@
+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 @@
+export {};

package/dist/llm/call-ai.js

@@ -0,0 +1,74 @@
+/**
+ * Unified AI call adapter: prefers `config.agent` (agent CLI shell-out),
+ * falls back to `config.llm` (HTTP chat-completions).
+ *
+ * NOT for use by background indexer passes — those call `chatCompletion`
+ * directly to avoid the agent-CLI overhead and to stay on the HTTP path that
+ * the indexer was designed around.
+ */
+import { warn } from "../core/warn";
+import { resolveAgentProfile, runAgent } from "../integrations/agent";
+import { chatCompletion } from "./client";
+/**
+ * Unified AI call: prefers `config.agent` (agent CLI), falls back to
+ * `config.llm` (HTTP). When neither is configured, returns a structured
+ * error pointing the user at `akm setup`.
+ *
+ * NOT for use by background indexer passes — those call `chatCompletion`
+ * directly.
+ */
+export async function callAi(config, prompt, opts = {}) {
+    if (config.agent) {
+        try {
+            const defaultName = config.agent.default;
+            if (!defaultName) {
+                return {
+                    ok: false,
+                    error: "No default agent profile configured. Set `agent.default` in config.json or run `akm setup`.",
+                };
+            }
+            const profile = resolveAgentProfile(defaultName, config.agent.profiles?.[defaultName]);
+            if (!profile) {
+                return {
+                    ok: false,
+                    error: `Agent profile "${defaultName}" 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) };
+        }
+    }
+    if (config.llm) {
+        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(config.llm, 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 `agent` or `llm` in your config.",
+    };
+}