akm-cli 0.7.5 → 0.8.0-rc.6

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,143 +46,83 @@ 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}`;
     }
-    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;
+    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,
+                ...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/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";

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.
  *

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.
  *

package/dist/llm/feature-gate.js

@@ -1,63 +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/.
 /**
- * Per-feature LLM gates (v1 spec §14).
- *
- * Every bounded in-tree LLM call site in akm is addressed by exactly one
- * feature key under `llm.features.*`. This module is the single seam call
- * sites use to ask "should I run?" and "if I run and fail, what do I return?"
- *
- * 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.
- *   - `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.
- *
- * Statelessness invariant (v1 spec §14.4): nothing in this module holds
- * state across calls. There are no caches, no module-level singletons, no
- * persistent connections. The architecture seam test
- * (`tests/architecture/llm-stateless-seam.test.ts`) does not currently
- * inspect this file but the same rule applies — keep all exports as pure
- * functions.
+ * For each feature key, return the effective enabled state by reading the
+ * new 0.8.0 config shape. Defaults match the legacy `LlmFeatureFlags` docstrings.
  */
+// Defaults below mirror the legacy LlmFeatureFlags docstrings so existing
+// behaviour is preserved when a config is silent on a flag.
+const FEATURE_LOCATION = {
+    // Legacy default: false → memory_consolidation only runs when explicitly enabled
+    // (either via the user's improve profile or the built-in `default` profile).
+    memory_consolidation: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.enabled ?? false,
+    // Legacy default: false
+    feedback_distillation: (cfg) => cfg.profiles?.improve?.default?.processes?.feedbackDistillation?.enabled ?? false,
+    // Legacy default: true
+    memory_inference: (cfg) => cfg.profiles?.improve?.default?.processes?.memoryInference?.enabled ?? true,
+    // Legacy default: true
+    graph_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.graphExtraction?.enabled ?? true,
+    // Legacy default: false
+    metadata_enhance: (cfg) => cfg.index?.metadataEnhance?.enabled ?? false,
+    // Legacy default: false
+    curate_rerank: (cfg) => cfg.search?.curateRerank?.enabled ?? false,
+    // Legacy default: false
+    lesson_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.distill?.qualityGate?.enabled ?? false,
+    // Legacy default: false
+    proposal_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.reflect?.qualityGate?.enabled ?? false,
+    // Legacy default: false
+    memory_contradiction_detection: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.contradictionDetection?.enabled ?? false,
+};
 /**
- * Pure predicate: is the named feature gate explicitly enabled in `config`?
+ * Pure predicate: is the named feature gate 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`.
+ * Reads from the unified 0.8.0 config shape. Defaults follow the legacy
+ * `LlmFeatureFlags` docstring defaults.
  */
 export function isLlmFeatureEnabled(config, feature) {
-    if (!config?.llm?.features)
+    if (!config)
+        return false;
+    const resolver = FEATURE_LOCATION[feature];
+    if (!resolver)
         return false;
-    return config.llm.features[feature] === true;
+    return resolver(config);
 }
-const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Default hard timeout for every bounded in-tree LLM call.
+ */
+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
  * thunk — the value produced by calling it).
- *
- * The fallback may be a value or a synchronous/async function returning a
- * value. The thunk form lets call sites encode "run the deterministic
- * pipeline" without paying for it in the success path:
- *
- * ```ts
- * const ranked = await tryLlmFeature(
- *   "curate_rerank",
- *   config,
- *   () => llmRerank(candidates),
- *   () => deterministicRerank(candidates),
- * );
- * ```
  */
 export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     const resolveFallback = async () => typeof fallback === "function" ? await fallback() : fallback;
@@ -79,6 +71,55 @@ export async function tryLlmFeature(feature, config, fn, fallback, opts) {
         return resolveFallback();
     }
 }
+/**
+ * Section-agnostic process gate. After the 0.8.0 migration, the canonical
+ * accessor is the `FEATURE_LOCATION` map above; this helper exists so older
+ * call sites that knew the (section, processName) pair don't all need to
+ * relearn the new mapping.
+ *
+ * For unknown (section, processName) pairs the result is `false`.
+ */
+export function isProcessEnabled(section, processName, config) {
+    if (!config)
+        return false;
+    // index.metadataEnhance / index.stalenessDetection are first-class new-shape entries.
+    if (section === "index") {
+        if (processName === "metadata_enhance" || processName === "metadataEnhance") {
+            return config.index?.metadataEnhance?.enabled ?? true;
+        }
+        if (processName === "staleness_detection" || processName === "stalenessDetection") {
+            return config.index?.stalenessDetection?.enabled ?? false;
+        }
+        if (processName === "memory_inference" || processName === "memoryInference") {
+            return isLlmFeatureEnabled(config, "memory_inference");
+        }
+        if (processName === "graph_extraction" || processName === "graphExtraction") {
+            return isLlmFeatureEnabled(config, "graph_extraction");
+        }
+    }
+    if (section === "search" && (processName === "curate_rerank" || processName === "curateRerank")) {
+        return config.search?.curateRerank?.enabled ?? false;
+    }
+    if (section === "improve") {
+        const processes = config.profiles?.improve?.default?.processes;
+        const entry = processes?.[processName];
+        if (entry && typeof entry.enabled === "boolean")
+            return entry.enabled;
+        // Fallback to default-enabled state for known processes.
+        switch (processName) {
+            case "reflect":
+            case "distill":
+            case "consolidate":
+            case "memoryInference":
+            case "graphExtraction":
+            case "feedbackDistillation":
+                return true;
+            default:
+                return false;
+        }
+    }
+    return false;
+}
 /** Specific error class so call sites and the wrapper can tell timeouts apart from generic throws. */
 export class LlmFeatureTimeoutError extends Error {
     feature;