akm-cli 0.7.5 → 0.8.0-rc2

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.",
+    };
+}

package/dist/llm/client.js

@@ -8,6 +8,10 @@
  * `llm.ts` re-exports everything from this module for backward compatibility.
  */
 import { fetchWithTimeout } from "../core/common";
+import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse";
+// Re-export shared parse utilities so existing importers of `client.ts` continue
+// to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
+export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse";
 /** Maximum length of an LLM error response body included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /**
@@ -38,143 +42,78 @@ export function redactErrorBody(input) {
     }
     return out;
 }
+export class LlmCallError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = "LlmCallError";
+    }
+}
 export async function chatCompletion(config, messages, options) {
     const timeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
         headers.Authorization = `Bearer ${config.apiKey}`;
     }
-    const response = await fetchWithTimeout(config.endpoint, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-            model: config.model,
-            messages,
-            temperature: options?.temperature ?? config.temperature ?? 0.3,
-            max_tokens: options?.maxTokens ?? config.maxTokens ?? 512,
-            ...config.extraParams,
-        }),
-    }, timeoutMs, options?.signal);
-    if (!response.ok) {
-        const rawBody = await response.text().catch(() => "");
-        const safeBody = redactErrorBody(rawBody);
-        throw new Error(`LLM request failed (${response.status}) ${config.endpoint}: ${safeBody}`);
+    // Only include max_tokens when explicitly set. The model/API knows its own
+    // limits; a hardcoded default creates silent truncation failures when the
+    // guess is wrong. Users who need a cap can set llm.maxTokens in config.
+    const resolvedMaxTokens = options?.maxTokens ?? config.maxTokens;
+    let response;
+    try {
+        response = await fetchWithTimeout(config.endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                model: config.model,
+                messages,
+                temperature: options?.temperature ?? config.temperature ?? 0.3,
+                ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
+                ...config.extraParams,
+            }),
+        }, timeoutMs, options?.signal);
     }
-    const json = (await response.json());
-    return json.choices?.[0]?.message?.content?.trim() ?? "";
-}
-/** Strip leading/trailing markdown code fences from an LLM response. */
-export function stripJsonFences(raw) {
-    const repaired = raw
-        .trim()
-        .replace(/<think>[\s\S]*?<\/think>/gi, "")
-        .replace(/^```(?:json)?\s*\n?/i, "")
-        .replace(/\n?```\s*$/i, "")
-        .trim();
-    let out = "";
-    let inString = false;
-    let escaped = false;
-    for (let i = 0; i < repaired.length; i++) {
-        const ch = repaired[i];
-        if (escaped) {
-            out += ch;
-            escaped = false;
-            continue;
+    catch (err) {
+        // fetchWithTimeout throws a plain Error with a message containing
+        // "timed out" for AbortController-driven timeouts, or "aborted" for
+        // caller-driven cancellations. Map both to typed LlmCallError.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new LlmCallError(`Request timed out after ${timeoutMs}ms`, "timeout");
         }
-        if (ch === "\\" && inString) {
-            out += ch;
-            escaped = true;
-            continue;
+        if (msg.includes("timed out")) {
+            throw new LlmCallError(`Request timed out after ${timeoutMs}ms`, "timeout");
         }
-        if (ch === '"') {
-            inString = !inString;
-            out += ch;
-            continue;
+        throw new LlmCallError(`Network error: ${msg}`, "network_error");
+    }
+    if (!response.ok) {
+        const rawBody = await response.text().catch(() => "");
+        const safeBody = redactErrorBody(rawBody);
+        const status = response.status;
+        if (status === 429) {
+            throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
         }
-        if (inString) {
-            if (ch === "\n") {
-                out += "\\n";
-                continue;
-            }
-            if (ch === "\r") {
-                out += "\\r";
-                continue;
-            }
-            if (ch === "\t") {
-                out += "\\t";
-                continue;
-            }
+        if (status >= 500) {
+            throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
         }
-        out += ch;
-    }
-    return out;
-}
-/** Parse a possibly-fenced JSON response. Returns undefined if invalid. */
-export function parseJsonResponse(raw) {
-    try {
-        return JSON.parse(stripJsonFences(raw));
-    }
-    catch {
-        return undefined;
+        throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
     }
+    const json = (await response.json());
+    const content = (json.choices?.[0]?.message?.content ?? "").trim();
+    const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
+    return content || reasoning;
 }
 /**
- * Best-effort recovery for providers that wrap JSON in extra prose or fenced
- * blocks. Extracts the first balanced top-level object/array and parses it.
+ * Strip `<think>` blocks, code fences, and escape control characters in JSON
+ * strings. Thin wrapper kept for backward compatibility with call sites that
+ * import `stripJsonFences` from this module. New code should prefer the
+ * granular helpers from `../core/parse`.
  */
-export function parseEmbeddedJsonResponse(raw) {
-    const direct = parseJsonResponse(raw);
-    if (direct !== undefined)
-        return direct;
-    const text = stripJsonFences(raw);
-    let arrayFallback;
-    for (let start = 0; start < text.length; start++) {
-        const opener = text[start];
-        if (opener !== "{" && opener !== "[")
-            continue;
-        const closer = opener === "{" ? "}" : "]";
-        let depth = 0;
-        let inString = false;
-        let escaped = false;
-        for (let i = start; i < text.length; i++) {
-            const ch = text[i];
-            if (inString) {
-                if (escaped) {
-                    escaped = false;
-                }
-                else if (ch === "\\") {
-                    escaped = true;
-                }
-                else if (ch === '"') {
-                    inString = false;
-                }
-                continue;
-            }
-            if (ch === '"') {
-                inString = true;
-                continue;
-            }
-            if (ch === opener)
-                depth += 1;
-            if (ch === closer) {
-                depth -= 1;
-                if (depth === 0) {
-                    try {
-                        const parsed = JSON.parse(text.slice(start, i + 1));
-                        if (!Array.isArray(parsed)) {
-                            return parsed;
-                        }
-                        arrayFallback ??= parsed;
-                        break;
-                    }
-                    catch {
-                        break;
-                    }
-                }
-            }
-        }
-    }
-    return arrayFallback;
+export function stripJsonFences(raw) {
+    return escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
 }
 // ── Availability check ──────────────────────────────────────────────────────
 /**

package/dist/llm/feature-gate.js

@@ -8,16 +8,15 @@
  * The seam is intentionally tiny:
  *
  *   - `isLlmFeatureEnabled(config, feature)` — pure predicate, no side
- *     effects, no I/O. Returns `true` only when the feature flag is the
- *     literal boolean `true` in config. Defaults are `false` per v1
- *     spec §14 — adding a flag to the schema is a non-event until the user
- *     opts in.
+ *     effects, no I/O. Returns `true` when the feature flag is explicitly
+ *     `true`, or when the feature has a non-false default (currently
+ *     `graph_extraction`).
  *   - `tryLlmFeature(feature, config, fn, fallback, opts?)` — single-call
  *     wrapper that runs `fn()` only when the gate is open, enforces a hard
- *     timeout (default 30s — overridable per call), and returns `fallback`
- *     on disablement, throw, or timeout. The wrapper is referentially
- *     transparent for any given (gate-state, fn-result) pair: no module
- *     state is mutated.
+ *     timeout (default 600s — overridable per call via `opts.timeoutMs`),
+ *     and returns `fallback` on disablement, throw, or timeout. The wrapper
+ *     is referentially transparent for any given (gate-state, fn-result)
+ *     pair: no module state is mutated.
  *
  * Statelessness invariant (v1 spec §14.4): nothing in this module holds
  * state across calls. There are no caches, no module-level singletons, no
@@ -29,18 +28,30 @@
 /**
  * Pure predicate: is the named feature gate explicitly enabled in `config`?
  *
- * Returns `false` when:
- *   - the LLM block is missing,
- *   - the `features` block is missing,
- *   - the key is absent (defaults are `false`),
- *   - the key is set to `false`.
+ * Returns `false` only when the key is explicitly set to `false`, or when
+ * the key is absent and its default is `false`.
  */
+const FEATURE_DEFAULTS = {
+    memory_inference: true,
+    graph_extraction: true,
+};
 export function isLlmFeatureEnabled(config, feature) {
-    if (!config?.llm?.features)
+    const configured = config?.llm?.features?.[feature];
+    if (configured === true)
+        return true;
+    if (configured === false)
         return false;
-    return config.llm.features[feature] === true;
+    return FEATURE_DEFAULTS[feature] === true;
 }
-const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Default hard timeout for every bounded in-tree LLM call. Set to 10 minutes
+ * (600 000 ms) — generous enough for a slow local model on a single-threaded
+ * server. Override per-call via `TryLlmFeatureOptions.timeoutMs`.
+ *
+ * Do NOT reduce this default without a documented user-facing reason — local
+ * model users need the headroom.
+ */
+const DEFAULT_TIMEOUT_MS = 600_000;
 /**
  * Run `fn()` only if `isLlmFeatureEnabled(config, feature)` is `true`. On
  * disablement, throw, or timeout, return `fallback` (or — if it is a