akm-cli 0.7.4 → 0.8.0-rc.3

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,105 +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,
-        }),
-    }, 30_000, options?.signal);
+    // 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);
+    }
+    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 (msg.includes("timed out")) {
+            throw new LlmCallError(`Request timed out after ${timeoutMs}ms`, "timeout");
+        }
+        throw new LlmCallError(`Network error: ${msg}`, "network_error");
+    }
     if (!response.ok) {
         const rawBody = await response.text().catch(() => "");
         const safeBody = redactErrorBody(rawBody);
-        throw new Error(`LLM request failed (${response.status}) ${config.endpoint}: ${safeBody}`);
+        const status = response.status;
+        if (status === 429) {
+            throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
+        }
+        if (status >= 500) {
+            throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
+        }
+        throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
     }
     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) {
-    return raw
-        .trim()
-        .replace(/<think>[\s\S]*?<\/think>/gi, "")
-        .replace(/^```(?:json)?\s*\n?/i, "")
-        .replace(/\n?```\s*$/i, "")
-        .trim();
-}
-/** Parse a possibly-fenced JSON response. Returns undefined if invalid. */
-export function parseJsonResponse(raw) {
-    try {
-        return JSON.parse(stripJsonFences(raw));
-    }
-    catch {
-        return undefined;
-    }
+    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