akm-cli 0.7.4 → 0.8.0-rc.10

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

package/dist/llm/client.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/.
 /**
  * Low-level OpenAI-compatible chat completions client and capability probing.
  *
@@ -8,6 +11,11 @@
  * `llm.ts` re-exports everything from this module for backward compatibility.
  */
 import { fetchWithTimeout } from "../core/common";
+import { resolveSecret } from "../core/config";
+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 +46,88 @@ 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 resolvedKey = resolveSecret(config.apiKey);
+    if (resolvedKey) {
+        headers.Authorization = `Bearer ${resolvedKey}`;
+    }
+    // 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;
+    const responseFormat = options?.responseSchema && config.supportsJsonSchema
+        ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
+        : {};
+    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 } : {}),
+                ...responseFormat,
+                ...(options?.enableThinking !== undefined
+                    ? { enable_thinking: options.enableThinking }
+                    : config.enableThinking !== undefined
+                        ? { enable_thinking: config.enableThinking }
+                        : {}),
+                ...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");
     }
-    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);
     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/embedder.js

@@ -1,22 +1,6 @@
-/**
- * Backward-compatible facade for the embedder module.
- *
- * The implementation has been split into:
- * - `./embedders/types`  — `EmbeddingVector`, `Embedder`, `EmbeddingCheckResult`
- * - `./embedders/local`  — `LocalEmbedder`, `DEFAULT_LOCAL_MODEL`,
- *                          `isTransformersAvailable`
- * - `./embedders/remote` — `RemoteEmbedder`, `hasRemoteEndpoint`
- * - `./embedders/cache`  — LRU `embedCache`, `clearEmbeddingCache`,
- *                          `embedCacheKey`
- *
- * This module wires them together: it picks the right implementation from the
- * (optional) embedding config, applies the cache layer, and re-exports the
- * existing public API so call sites (`db-search.ts`, `indexer.ts`, `db.ts`,
- * `setup.ts`, `semantic-status.ts`, tests) keep working unmodified.
- *
- * Tests can construct fresh `LocalEmbedder` / `RemoteEmbedder` instances
- * directly from their submodules to avoid module-level state pollution.
- */
+// 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 { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache";
 import { isTransformersAvailable, LocalEmbedder } from "./embedders/local";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote";
@@ -24,18 +8,25 @@ import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote";
 export { clearEmbeddingCache } from "./embedders/cache";
 export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local";
 // ── Singleton local embedder ────────────────────────────────────────────────
-// `localEmbedder` is an intentional module-level singleton. The underlying
-// @huggingface/transformers pipeline is expensive to initialise (model download
-// + WASM compilation) and is safe to share across calls because it is
-// stateless once created. Storing it here avoids re-initialising on every
-// embed() call.
-const localEmbedder = new LocalEmbedder();
+// `_localEmbedder` is an intentional module-level singleton but constructed
+// lazily on first use. The underlying @huggingface/transformers pipeline is
+// expensive to initialise (model download + WASM compilation) and is safe to
+// share across calls because it is stateless once created. Deferring
+// construction to first call keeps the module side-effect-free at import time,
+// which matters for the test suite (single Bun process, ~120 test files).
+let _localEmbedder;
+function getLocalEmbedder() {
+    if (!_localEmbedder) {
+        _localEmbedder = new LocalEmbedder();
+    }
+    return _localEmbedder;
+}
 /**
  * Reset the cached local embedder pipeline. Used by tests that want a fresh
  * pipeline construction (e.g. to assert the dtype-fallback retry logic).
  */
 export function resetLocalEmbedder() {
-    localEmbedder.reset();
+    getLocalEmbedder().reset();
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
@@ -54,7 +45,7 @@ export async function embed(text, embeddingConfig, signal) {
         return cached;
     const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
         ? await new RemoteEmbedder(embeddingConfig).embed(text, signal)
-        : await localEmbedder.embed(text, signal);
+        : await getLocalEmbedder().embed(text, signal);
     setCachedEmbedding(key, result);
     return result;
 }
@@ -76,7 +67,7 @@ export async function embedBatch(texts, embeddingConfig, signal) {
         if (signal?.aborted) {
             throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
         }
-        results.push(await localEmbedder.embedWithModel(text, localModel));
+        results.push(await getLocalEmbedder().embedWithModel(text, localModel));
     }
     return results;
 }
@@ -113,7 +104,7 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
         };
     }
     try {
-        await localEmbedder.getPipeline(embeddingConfig?.localModel);
+        await getLocalEmbedder().getPipeline(embeddingConfig?.localModel);
         return { available: true };
     }
     catch (err) {

package/dist/llm/embedders/cache.js

@@ -1,10 +1,6 @@
-/**
- * LRU embedding cache shared by the embedder facade.
- *
- * Caches query embeddings to avoid redundant computation for repeated
- * queries. Uses a simple Map with LRU eviction (delete + re-insert to move
- * an entry to the most-recently-used end).
- */
+// 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/.
 const EMBED_CACHE_MAX = 100;
 const embedCache = new Map();
 /**

package/dist/llm/embedders/local.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/.
 /**
  * Local @huggingface/transformers embedder.
  *
@@ -25,6 +28,31 @@ const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
 function resolveLocalModelName(overrideModel) {
     return overrideModel || DEFAULT_LOCAL_MODEL;
 }
+/**
+ * Detect whether the current process is running from a Bun-compiled binary
+ * (i.e. `bun build --compile` produced a single executable). Bun marks the
+ * compiled binary with a synthesized `process.execPath` that ends in the
+ * binary name rather than `bun`, AND sets a flag we can probe.
+ *
+ * Used to gate the "install @huggingface/transformers" hint — that advice
+ * is impossible to follow from a single-binary install, so we replace it
+ * with the only working remediation (switch to npm/Bun install, or turn
+ * semantic search off). See #482.
+ */
+function isCompiledBinary() {
+    try {
+        const flag = Bun.embeddedFiles;
+        if (flag !== undefined)
+            return true;
+    }
+    catch {
+        // Bun not available (under Node tests, for example) — treat as not-binary.
+    }
+    const exec = (process.execPath || "").toLowerCase();
+    if (exec.endsWith("/akm") || exec.endsWith("\\akm.exe"))
+        return true;
+    return false;
+}
 export class LocalEmbedder {
     defaultModel;
     /**
@@ -93,7 +121,20 @@ export class LocalEmbedder {
                 catch (importError) {
                     const msg = importError instanceof Error ? importError.message : String(importError);
                     if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
-                        throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
+                        // #482: the prebuilt binary build is invoked with
+                        // `bun install --omit optional` (release.yml), so binary users
+                        // can NEVER load @huggingface/transformers. Telling them to
+                        // `bun add` it is a dead-end — there is no install target.
+                        // Detect the binary execution path and give the only working
+                        // remediation: switch to the npm/Bun install of akm-cli, or
+                        // turn off semantic search.
+                        const isBinary = isCompiledBinary();
+                        const hint = isBinary
+                            ? "You are running the prebuilt akm binary, which cannot load optional native dependencies. " +
+                                "To enable semantic search, install akm-cli via Bun: `curl -fsSL https://bun.sh/install | bash && bun install -g akm-cli`. " +
+                                "To keep using the binary, set `semanticSearchMode: off` in your config and use keyword-only FTS."
+                            : "Install it with: `bun add @huggingface/transformers` (or `npm install @huggingface/transformers`).";
+                        throw new Error(`Semantic search requires @huggingface/transformers. ${hint}`);
                     }
                     throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
                 }

package/dist/llm/embedders/remote.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/.
 /**
  * OpenAI-compatible remote embedder.
  *
@@ -5,6 +8,7 @@
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
 import { fetchWithTimeout, isHttpUrl } from "../../core/common";
+import { resolveSecret } from "../../core/config";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
 export function estimateTokenCount(text) {
@@ -12,14 +16,21 @@ export function estimateTokenCount(text) {
 }
 export class RemoteEmbedder {
     config;
+    endpoint;
+    model;
     constructor(config) {
         this.config = config;
+        if (!config.endpoint || !config.model) {
+            throw new Error("RemoteEmbedder requires both endpoint and model on the embedding config.");
+        }
+        this.endpoint = config.endpoint;
+        this.model = config.model;
     }
     async embed(text, signal) {
         const headers = this.buildHeaders();
         const body = {
             input: text,
-            model: this.config.model,
+            model: this.model,
         };
         if (this.config.dimension) {
             body.dimensions = this.config.dimension;
@@ -28,7 +39,7 @@ export class RemoteEmbedder {
         if (ollamaOpts) {
             body.options = ollamaOpts;
         }
-        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
+        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.endpoint), {
             method: "POST",
             headers,
             body: JSON.stringify(body),
@@ -40,7 +51,7 @@ export class RemoteEmbedder {
         }
         const json = (await response.json());
         if (!json.data?.[0]?.embedding) {
-            throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(this.config.endpoint)}`);
+            throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(this.endpoint)}`);
         }
         return l2Normalize(json.data[0].embedding);
     }
@@ -55,7 +66,7 @@ export class RemoteEmbedder {
             const batch = texts.slice(i, i + batchSize);
             const body = {
                 input: batch,
-                model: this.config.model,
+                model: this.model,
             };
             if (this.config.dimension) {
                 body.dimensions = this.config.dimension;
@@ -63,7 +74,7 @@ export class RemoteEmbedder {
             if (ollamaOpts) {
                 body.options = ollamaOpts;
             }
-            const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
+            const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.endpoint), {
                 method: "POST",
                 headers,
                 body: JSON.stringify(body),
@@ -75,7 +86,7 @@ export class RemoteEmbedder {
             }
             const json = (await response.json());
             if (!json.data || json.data.length !== batch.length) {
-                throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(this.config.endpoint)}`);
+                throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(this.endpoint)}`);
             }
             // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
             const sorted = [...json.data].sort((a, b) => a.index - b.index);
@@ -90,8 +101,9 @@ export class RemoteEmbedder {
     }
     buildHeaders() {
         const headers = { "Content-Type": "application/json" };
-        if (this.config.apiKey) {
-            headers.Authorization = `Bearer ${this.config.apiKey}`;
+        const resolvedKey = resolveSecret(this.config.apiKey);
+        if (resolvedKey) {
+            headers.Authorization = `Bearer ${resolvedKey}`;
         }
         return headers;
     }

package/dist/llm/embedders/types.js

@@ -1,10 +1,6 @@
-/**
- * Shared embedder types.
- *
- * Pulled out of `embedder.ts` so concrete implementations (`local.ts`,
- * `remote.ts`) and the cache layer can depend on a small, stable types
- * module without dragging in the facade or a sibling implementation.
- */
+// 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/.
 /**
  * Cosine similarity between two embedding vectors.
  *