akm-cli 0.9.0-beta.53 → 0.9.0-beta.55

package/dist/indexer/index-writer-lock.js

@@ -7,6 +7,7 @@ import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
 const INDEX_WRITER_LOCK_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
 const INDEX_WRITER_WAIT_MS = 100;
+const DEFAULT_INDEX_WRITER_MAX_WAIT_MS = 10 * 60 * 1000;
 const heldLocks = new Map();
 function buildPayload(purpose, pid = process.pid) {
     return JSON.stringify({
@@ -49,17 +50,23 @@ function retainHeldLock(lockPath) {
 export async function acquireIndexWriterLease(options) {
     const mode = options.mode ?? "wait";
     const lockPath = getIndexWriterLockPath();
+    const startedAt = Date.now();
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_INDEX_WRITER_MAX_WAIT_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     if (heldLocks.has(lockPath)) {
+        options.onAcquired?.({ waitedMs: 0 });
         return retainHeldLock(lockPath);
     }
+    let lastWaitNoticeMs = 0;
     while (true) {
         throwIfAborted(options.signal);
         if (tryAcquireLockSync(lockPath, buildPayload(options.purpose))) {
+            options.onAcquired?.({ waitedMs: Date.now() - startedAt });
             return retainHeldLock(lockPath);
         }
         const probe = probeLock(lockPath, { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
         if (probe.state === "held" && probe.holderPid === process.pid) {
+            options.onAcquired?.({ waitedMs: Date.now() - startedAt });
             return retainHeldLock(lockPath);
         }
         if (probe.state === "stale") {
@@ -68,6 +75,17 @@ export async function acquireIndexWriterLease(options) {
         }
         if (mode === "try")
             return undefined;
+        // Held by another live process. Time out only *after* a real acquisition
+        // attempt, so a caller with maxWaitMs:0 still gets one chance at a free lock
+        // instead of throwing before it ever tries.
+        if (maxWaitMs >= 0 && Date.now() - startedAt >= maxWaitMs) {
+            throw new Error(`timed out waiting for index writer lease for ${options.purpose}`);
+        }
+        const waitedMs = Date.now() - startedAt;
+        if (waitedMs - lastWaitNoticeMs >= 15000) {
+            options.onWait?.({ waitedMs });
+            lastWaitNoticeMs = waitedMs;
+        }
         await delay(INDEX_WRITER_WAIT_MS);
     }
 }

package/dist/indexer/indexer.js

@@ -118,7 +118,7 @@ async function runWalkPhase(ctx) {
     ctx.timing.tWalkEnd = Date.now();
     throwIfAborted(signal);
     // LLM enrichment for directories that need it
-    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, true, reEnrich);
+    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich);
     onProgress({
         phase: "llm",
         message: resolveIndexPassLLM("enrichment", config)
@@ -143,6 +143,7 @@ async function runEmbeddingPhase(ctx) {
  */
 async function runFinalizePhase(ctx) {
     const { db, config, sources, sourceDirs, isIncremental, stashDir, signal, onProgress } = ctx;
+    ctx.timing.tFinalizeStart = Date.now();
     // Rebuild FTS after all inserts. Use incremental mode when this whole
     // index run is incremental — only entries touched by `upsertEntry`
     // since the last rebuild are re-indexed.
@@ -153,10 +154,13 @@ async function runFinalizePhase(ctx) {
     });
     ctx.timing.tFtsEnd = Date.now();
     // Re-link detached usage_events and recompute utility scores.
+    onProgress({ phase: "finalize", message: "Relinking usage events." });
     relinkUsageEvents(db);
+    onProgress({ phase: "finalize", message: "Recomputing utility scores." });
     recomputeUtilityScores(db);
     // Purge LLM cache entries for assets that no longer exist in the index.
     try {
+        onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
         clearStaleCacheEntries(db);
     }
     catch {
@@ -164,6 +168,7 @@ async function runFinalizePhase(ctx) {
     }
     // Regenerate each wiki's index.md from its pages' frontmatter. Best-effort.
     try {
+        onProgress({ phase: "finalize", message: "Regenerating wiki indexes." });
         const { regenerateAllWikiIndexes } = await import("../wiki/wiki.js");
         regenerateAllWikiIndexes(stashDir);
     }
@@ -180,6 +185,7 @@ async function runFinalizePhase(ctx) {
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
     const semanticEntryCount = getEmbeddableEntryCount(db);
+    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
     const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
     if (config.semanticSearchMode === "off") {
         clearSemanticStatus();
@@ -199,6 +205,7 @@ async function runFinalizePhase(ctx) {
     // Store verification result and totalEntries on ctx for the caller to use
     ctx.verification = verification;
     ctx.totalEntries = totalEntries;
+    ctx.timing.tFinalizeEnd = Date.now();
     // suppress unused warning — sources was previously used inline
     void sources;
 }
@@ -226,8 +233,34 @@ function runCleanPass(db, dryRun) {
     };
 }
 // ── Indexer ──────────────────────────────────────────────────────────────────
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let akmIndexOverride;
+/** TEST-ONLY. Swap the implementation of `akmIndex`; pass undefined to restore. */
+export function _setAkmIndexForTests(fake) {
+    akmIndexOverride = fake;
+}
 export async function akmIndex(options) {
-    return withIndexWriterLease({ purpose: "akm-index", signal: options?.signal }, async () => {
+    if (akmIndexOverride)
+        return akmIndexOverride(options);
+    return akmIndexReal(options);
+}
+async function akmIndexReal(options) {
+    const requestedAt = Date.now();
+    let acquiredAt = requestedAt;
+    return withIndexWriterLease({
+        purpose: "akm-index",
+        signal: options?.signal,
+        onWait: ({ waitedMs }) => {
+            options?.onProgress?.({
+                phase: "preflight",
+                message: `Waiting for index writer lease (${Math.round(waitedMs / 1000)}s elapsed).`,
+            });
+        },
+        onAcquired: ({ waitedMs }) => {
+            acquiredAt = requestedAt + waitedMs;
+        },
+    }, async () => {
         const stashDir = options?.stashDir || resolveStashDir();
         const onProgress = options?.onProgress ?? (() => { });
         const signal = options?.signal;
@@ -246,10 +279,17 @@ export async function akmIndex(options) {
         warnOnUnmigratedVaults(stashDir);
         // Ensure git stash caches are extracted before resolving stash dirs,
         // so their content directories exist on disk for the walker to discover.
+        const sourceCacheStart = Date.now();
+        onProgress({ phase: "preflight", message: "Hydrating source caches." });
         const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
         await ensureSourceCaches(config, { force: full });
+        const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
         const allSourceDirs = allSourceEntries.map((s) => s.path);
+        onProgress({
+            phase: "preflight",
+            message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
+        });
         const t0 = Date.now();
         // Open database — pass embedding dimension from config if available
         const dbPath = getDbPath();
@@ -279,6 +319,8 @@ export async function akmIndex(options) {
                     tLlmEnd: t0,
                     tFtsEnd: t0,
                     tEmbedEnd: t0,
+                    tFinalizeStart: t0,
+                    tFinalizeEnd: t0,
                 },
                 isIncremental,
                 builtAtMs,
@@ -316,9 +358,15 @@ export async function akmIndex(options) {
             // After the normal index completes, remove entries whose source files no
             // longer exist on disk. Remote entries (empty file_path) are skipped.
             let cleanResult;
+            const cleanStart = Date.now();
             if (clean) {
+                onProgress({
+                    phase: "finalize",
+                    message: dryRun ? "Scanning for stale index entries (dry run)." : "Removing stale index entries.",
+                });
                 cleanResult = runCleanPass(db, dryRun);
             }
+            const cleanEnd = Date.now();
             // ────────────────────────────────────────────────────────────────────────
             return {
                 stashDir,
@@ -336,6 +384,12 @@ export async function akmIndex(options) {
                     llmMs: timing.tLlmEnd - timing.tWalkEnd,
                     embedMs: timing.tEmbedEnd - timing.tLlmEnd,
                     ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
+                    finalizeMs: timing.tFinalizeEnd - timing.tFinalizeStart,
+                    cleanMs: clean ? cleanEnd - cleanStart : 0,
+                    preflightMs: timing.t0 - requestedAt,
+                    leaseWaitMs: acquiredAt - requestedAt,
+                    sourceCacheMs: sourceCacheEnd - sourceCacheStart,
+                    endToEndMs: Date.now() - requestedAt,
                 },
                 ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
             };
@@ -640,7 +694,7 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadR
     insertTransaction();
     return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
-async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, _enrich = false, reEnrich = false) {
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich = false) {
     // Resolve per-pass LLM config via the unified shim. Returns undefined when
     // either no `akm.llm` is configured or the user opted this pass out via
     // `index.enrichment.llm = false`. (#208)
@@ -842,31 +896,44 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
                 warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
             }
         }
-        const embeddings = await embedBatch(texts, config.embedding, signal);
-        throwIfAborted(signal);
-        // Wrap all embedding upserts in a single transaction so partial
-        // state is rolled back on failure rather than leaving the table half-filled.
-        let storedCount = 0;
-        let skippedCount = 0;
-        db.transaction(() => {
-            for (let i = 0; i < allEntries.length; i++) {
-                if (upsertEmbedding(db, allEntries[i].id, embeddings[i])) {
-                    storedCount++;
-                }
-                else {
-                    skippedCount++;
+        let heartbeatTimer;
+        try {
+            heartbeatTimer = setInterval(() => {
+                onProgress({
+                    phase: "embeddings",
+                    message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
+                });
+            }, 15000);
+            const embeddings = await embedBatch(texts, config.embedding, signal);
+            throwIfAborted(signal);
+            // Wrap all embedding upserts in a single transaction so partial
+            // state is rolled back on failure rather than leaving the table half-filled.
+            let storedCount = 0;
+            let skippedCount = 0;
+            db.transaction(() => {
+                for (let i = 0; i < allEntries.length; i++) {
+                    if (upsertEmbedding(db, allEntries[i].id, embeddings[i])) {
+                        storedCount++;
+                    }
+                    else {
+                        skippedCount++;
+                    }
                 }
+            })();
+            if (skippedCount > 0) {
+                warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
-        })();
-        if (skippedCount > 0) {
-            warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
+            onProgress({
+                phase: "embeddings",
+                message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
+            });
+            setMeta(db, "embeddingFingerprint", currentFingerprint);
+            return { success: true };
+        }
+        finally {
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
         }
-        onProgress({
-            phase: "embeddings",
-            message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
-        });
-        setMeta(db, "embeddingFingerprint", currentFingerprint);
-        return { success: true };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -977,7 +1044,7 @@ function resolveIndexedFiles(dirPath, files, stash) {
     for (const entry of stash.entries) {
         const entryPath = entry.filename
             ? path.join(dirPath, entry.filename)
-            : matchEntryToFile(entry.name, fileBasenameMap, files);
+            : matchEntryToFile(entry.name, fileBasenameMap);
         if (entryPath)
             resolved.add(entryPath);
     }
@@ -1096,7 +1163,7 @@ export function buildFileBasenameMap(files) {
  *      try matching the last segment
  *   3. No implicit file fallback: ambiguous legacy entries are skipped
  */
-export function matchEntryToFile(entryName, fileMap, _files) {
+export function matchEntryToFile(entryName, fileMap) {
     // Exact match on entry name
     const exact = fileMap.get(entryName);
     if (exact)

package/dist/indexer/read-preflight.js

@@ -0,0 +1,23 @@
+// 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 { ensureIndex } from "./ensure-index.js";
+import { resolveSourceEntries } from "./search/search-source.js";
+/** Resolve the active read sources using the same resolution rules as search/show. */
+export function resolveReadSources(overrideStashDir, existingConfig) {
+    const sources = resolveSourceEntries(overrideStashDir, existingConfig);
+    return { sources, primarySource: sources[0] };
+}
+/** Ensure the primary source index is readable for reads, when a primary exists. */
+export async function ensurePrimaryIndexForRead(primarySource) {
+    if (!primarySource?.path)
+        return false;
+    return ensureIndex(primarySource.path);
+}
+/**
+ * Convenience helper for callers that only need to ensure a read index from a
+ * configured stash path and default config.
+ */
+export async function ensurePrimaryIndexFromConfig(overrideStashDir, existingConfig) {
+    return ensurePrimaryIndexForRead(resolveReadSources(overrideStashDir, existingConfig).primarySource);
+}

package/dist/indexer/search/fts-query.js

@@ -0,0 +1,51 @@
+// 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/.
+/**
+ * Pure FTS5 query-string helpers, extracted from indexer/db/db.ts.
+ *
+ * These transform a raw user query into an FTS5-safe MATCH expression. They
+ * touch no database state, so they are unit-testable with zero DB setup.
+ */
+/**
+ * Sanitize a raw user query into an FTS5-safe implicit-AND expression.
+ *
+ * Allows only characters safe in FTS5 queries: letters, digits, underscores,
+ * and whitespace. Everything else (hyphens, dots, quotes, parens, asterisks,
+ * colons, carets, @, !, etc.) is replaced with a space so that compound
+ * identifiers like "code-review" or "k8s.setup" become AND-joined tokens
+ * ("code review", "k8s setup") rather than triggering FTS5 syntax errors.
+ */
+export function sanitizeFtsQuery(query) {
+    let sanitized = query.replace(/[^a-zA-Z0-9_\s]/g, " ");
+    // Neutralize the NEAR operator (FTS5 proximity syntax)
+    sanitized = sanitized.replace(/\bNEAR\b/g, " ");
+    const tokens = sanitized.split(/\s+/).filter((t) => t.length >= 1);
+    if (tokens.length === 0)
+        return "";
+    // Use implicit AND (space-separated tokens) for precision. FTS5 treats
+    // space-separated tokens as an implicit AND, matching only rows that
+    // contain ALL terms.
+    return tokens.join(" ");
+}
+/**
+ * Build a prefix query from an FTS5 query string by appending `*` to each
+ * token that is 3+ characters long. Tokens shorter than 3 characters are
+ * kept as-is (no prefix expansion) to avoid overly broad matches.
+ *
+ * Returns null if no tokens qualify for prefix expansion.
+ */
+export function buildPrefixQuery(ftsQuery) {
+    const tokens = ftsQuery.split(/\s+/).filter(Boolean);
+    let hasPrefix = false;
+    const prefixTokens = tokens.map((t) => {
+        if (t.length >= 3) {
+            hasPrefix = true;
+            return `${t}*`;
+        }
+        return t;
+    });
+    if (!hasPrefix)
+        return null;
+    return prefixTokens.join(" ");
+}

package/dist/indexer/walk/walker.js

@@ -148,20 +148,28 @@ function isInsideGitRepo(dir) {
  * read (e.g. permission errors).
  */
 export function* walkMarkdownFiles(root) {
-    let entries;
-    try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const full = path.join(root, entry.name);
-        if (entry.isDirectory()) {
-            yield* walkMarkdownFiles(full);
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
         }
-        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-            yield full;
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+                yield full;
+            }
         }
     }
 }

package/dist/integrations/agent/detect.js

@@ -55,6 +55,11 @@ export function defaultWhich(bin, envSource = process.env) {
     }
     return undefined;
 }
+let detectOverrides;
+/** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */
+export function _setAgentDetectForTests(fakes) {
+    detectOverrides = fakes;
+}
 /**
  * Probe every resolvable agent profile (built-ins plus user overrides)
  * for an installed CLI.
@@ -64,6 +69,8 @@ export function defaultWhich(bin, envSource = process.env) {
  * @param whichFn  Binary lookup. Tests should inject a stub.
  */
 export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
+    if (detectOverrides?.detectAgentCliProfiles)
+        return detectOverrides.detectAgentCliProfiles(agent, whichFn);
     const profiles = listResolvedAgentProfiles(agent);
     return profiles.map((profile) => probeProfile(profile, whichFn));
 }
@@ -87,6 +94,8 @@ function probeProfile(profile, whichFn) {
  *      writing `agent.default`.
  */
 export function pickDefaultAgentProfile(results, existingDefault) {
+    if (detectOverrides?.pickDefaultAgentProfile)
+        return detectOverrides.pickDefaultAgentProfile(results, existingDefault);
     if (existingDefault) {
         const match = results.find((r) => r.name === existingDefault && r.available);
         if (match)

package/dist/integrations/agent/index.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 export { getCommandBuilder } from "./builders.js";
 export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
-export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
+export { _setAgentDetectForTests, defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
 export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "./prompts.js";

package/dist/integrations/agent/spawn.js

@@ -17,6 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { spawn as runtimeSpawn } from "../../runtime.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
@@ -346,72 +347,20 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     if (parseOutput === "json" && stdioMode === "captured") {
-        // Strip <think> blocks and code fences, then try direct parse with
-        // embedded-JSON fallback for local LLMs that emit prose around the payload.
-        const cleaned = stdout
-            .trim()
-            .replace(/<think>[\s\S]*?<\/think>/gi, "")
-            .trim()
-            .replace(/^```(?:json)?\s*\n?/, "")
-            .replace(/\n?```\s*$/, "")
-            .trim();
-        let parsed;
-        try {
-            parsed = JSON.parse(cleaned);
-        }
-        catch {
-            // Fallback: extract the first balanced {…} from prose output.
-            let found;
-            for (let s = 0; s < cleaned.length; s++) {
-                if (cleaned[s] !== "{")
-                    continue;
-                let depth = 0, inStr = false, esc = false;
-                for (let i = s; i < cleaned.length; i++) {
-                    const c = cleaned[i];
-                    if (inStr) {
-                        if (esc) {
-                            esc = false;
-                        }
-                        else if (c === "\\") {
-                            esc = true;
-                        }
-                        else if (c === '"') {
-                            inStr = false;
-                        }
-                        continue;
-                    }
-                    if (c === '"') {
-                        inStr = true;
-                        continue;
-                    }
-                    if (c === "{")
-                        depth++;
-                    if (c === "}") {
-                        depth--;
-                        if (depth === 0) {
-                            try {
-                                found = JSON.parse(cleaned.slice(s, i + 1));
-                            }
-                            catch { }
-                            break;
-                        }
-                    }
-                }
-                if (found !== undefined)
-                    break;
-            }
-            if (found === undefined) {
-                return {
-                    ok: false,
-                    exitCode,
-                    stdout,
-                    stderr,
-                    durationMs,
-                    reason: "parse_error",
-                    error: "no JSON object found in agent output",
-                };
-            }
-            parsed = found;
+        // Strip <think> blocks and code fences, then parse with embedded-JSON
+        // fallback for local LLMs that emit prose around the payload. Handles
+        // both top-level `{…}` and `[…]` structures.
+        const parsed = parseEmbeddedJsonResponse(stdout);
+        if (parsed === undefined) {
+            return {
+                ok: false,
+                exitCode,
+                stdout,
+                stderr,
+                durationMs,
+                reason: "parse_error",
+                error: "no JSON structure found in agent output",
+            };
         }
         return { ok: true, exitCode, stdout, stderr, durationMs, parsed };
     }

package/dist/llm/client.js

@@ -165,7 +165,19 @@ function isRetryable(err) {
     }
     return false;
 }
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let chatCompletionOverride;
+/** TEST-ONLY. Swap the implementation of `chatCompletion`; pass undefined to restore. */
+export function _setChatCompletionForTests(fake) {
+    chatCompletionOverride = fake;
+}
 export async function chatCompletion(config, messages, options) {
+    if (chatCompletionOverride)
+        return chatCompletionOverride(config, messages, options);
+    return chatCompletionReal(config, messages, options);
+}
+async function chatCompletionReal(config, messages, options) {
     const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
     const started = Date.now();
     try {

package/dist/llm/embedder.js

@@ -3,11 +3,26 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
 import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
-import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable as isTransformersAvailableReal, LocalEmbedder, } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
-export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local.js";
+export { _setTransformersLoaderForTests, DEFAULT_LOCAL_MODEL } from "./embedders/local.js";
+let embedderOverrides;
+/** TEST-ONLY. Swap embedder implementations; pass undefined to restore. */
+export function _setEmbedderForTests(fakes) {
+    embedderOverrides = fakes;
+}
+/**
+ * Check whether the @huggingface/transformers package is importable.
+ * Delegating wrapper around `./embedders/local`'s probe so tests can swap it
+ * via {@link _setEmbedderForTests}.
+ */
+export function isTransformersAvailable() {
+    if (embedderOverrides?.isTransformersAvailable)
+        return embedderOverrides.isTransformersAvailable();
+    return isTransformersAvailableReal();
+}
 // ── Singleton local embedder ────────────────────────────────────────────────
 // `_localEmbedder` is an intentional module-level singleton but constructed
 // lazily on first use. The underlying @huggingface/transformers pipeline is
@@ -40,6 +55,8 @@ export function resetLocalEmbedder() {
  * and embedding config. Repeated identical queries return the cached vector.
  */
 export async function embed(text, embeddingConfig, signal) {
+    if (embedderOverrides?.embed)
+        return embedderOverrides.embed(text, embeddingConfig, signal);
     // Deterministic mode (env-gated, test/bench only): model-free, stable.
     if (isDeterministicEmbedEnabled()) {
         return deterministicEmbed(text);
@@ -61,6 +78,8 @@ export async function embed(text, embeddingConfig, signal) {
  * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
+    if (embedderOverrides?.embedBatch)
+        return embedderOverrides.embedBatch(texts, embeddingConfig, signal);
     if (texts.length === 0)
         return [];
     // Deterministic mode (env-gated, test/bench only): model-free, stable.
@@ -104,6 +123,8 @@ export { cosineSimilarity } from "./embedders/types.js";
  *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
  */
 export function resolveEmbeddingModelId(embeddingConfig) {
+    if (embedderOverrides?.resolveEmbeddingModelId)
+        return embedderOverrides.resolveEmbeddingModelId(embeddingConfig);
     if (isDeterministicEmbedEnabled())
         return DETERMINISTIC_EMBED_MODEL_ID;
     if (!embeddingConfig)
@@ -117,6 +138,9 @@ export function resolveEmbeddingModelId(embeddingConfig) {
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
+    if (embedderOverrides?.checkEmbeddingAvailability) {
+        return embedderOverrides.checkEmbeddingAvailability(embeddingConfig);
+    }
     // Deterministic mode (env-gated): always available — no model, no network.
     if (isDeterministicEmbedEnabled()) {
         return { available: true };

package/dist/llm/embedders/local.js

@@ -28,6 +28,12 @@ function isBatchTensor(v) {
         Array.isArray(v.dims) &&
         v.dims.length >= 2);
 }
+const realTransformersLoader = () => import("@huggingface/transformers");
+let transformersLoader = realTransformersLoader;
+/** TEST-ONLY. Swap the transformers module loader; pass undefined to restore. */
+export function _setTransformersLoaderForTests(fake) {
+    transformersLoader = fake ?? realTransformersLoader;
+}
 const LOCAL_EMBEDDER_DTYPE = "fp32";
 const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
 /**
@@ -180,7 +186,7 @@ export class LocalEmbedder {
                 }
                 let pipeline;
                 try {
-                    const mod = await import("@huggingface/transformers");
+                    const mod = await transformersLoader();
                     pipeline = mod.pipeline;
                 }
                 catch (importError) {