akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/llm/feature-gate.js

@@ -1,63 +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/.
 /**
- * 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,
+    // 0.8.0 unified gate: replaces the legacy `feedback_distillation` key.
+    // The orchestration gate (planner) and the LLM-call gate now share the same
+    // source of truth: `processes.distill.enabled`. Default: true (matches the
+    // built-in `default` profile).
+    distill: (cfg) => cfg.profiles?.improve?.default?.processes?.distill?.enabled ?? true,
+    // 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,
+    // Default: true. Session extraction replaces the akm-plugin checkpoint hook
+    // and is the primary path for capturing durable signal from real sessions.
+    // Opt out via `profiles.improve.default.processes.extract.enabled: false`.
+    session_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.extract?.enabled ?? true,
+};
 /**
- * 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 +78,54 @@ 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":
+                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;