akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/llm/client.js

@@ -8,13 +8,11 @@
  * probing, and availability checks) separate from higher-level workflows.
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
-import { resolveSecret } from "../core/config/config.js";
-import { isApiKeyReference } from "../core/config/schema/primitives.js";
+import { openAiBaseUrl, openAiOperationUrl } from "../core/endpoint-url.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
-import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
+import { effectiveRequestFields } from "../core/llm-inference.js";
+import { redactErrorBody, redactSensitiveText, redactUrlCredentials } from "../core/redaction.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
-import { resolveSecretFromStore } from "../sources/snapshot-fetchers/secret-seam.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
 /** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
@@ -183,25 +181,37 @@ export async function chatCompletion(config, messages, options) {
         return chatCompletionOverride(config, messages, options);
     return chatCompletionReal(config, messages, options);
 }
+/**
+ * One call's time budget: the first attempt is given all of it and a retry
+ * only what is left, so a call and its retries never outlast its timeout.
+ */
+function timeBudget(totalMs) {
+    if (totalMs === null)
+        return () => null;
+    let deadlineAt;
+    return () => {
+        const now = Date.now();
+        deadlineAt ??= now + totalMs;
+        return Math.max(0, deadlineAt - now);
+    };
+}
 async function chatCompletionReal(config, messages, options) {
     const effectiveTimeoutMs = options && Object.hasOwn(options, "timeoutMs")
         ? (options.timeoutMs ?? null)
         : Object.hasOwn(config, "timeoutMs")
             ? (config.timeoutMs ?? null)
-            : DEFAULT_LLM_TIMEOUT_MS;
+            : null;
     const started = Date.now();
+    const budget = timeBudget(effectiveTimeoutMs);
     try {
-        return await chatCompletionAttempt(config, messages, options, effectiveTimeoutMs);
+        return await chatCompletionAttempt(config, messages, options, budget);
     }
     catch (err) {
         if (!(err instanceof LlmCallError) || !isRetryable(err))
             throw err;
         // Timeout-budget guard: if the first attempt already burned most of the
         // budget, a second attempt cannot complete — skip the retry.
-        const elapsed = Date.now() - started;
-        const remaining = effectiveTimeoutMs === null ? null : effectiveTimeoutMs - elapsed;
-        if (effectiveTimeoutMs !== null &&
-            (elapsed >= effectiveTimeoutMs * RETRY_BUDGET_FRACTION || (remaining !== null && remaining <= 0))) {
+        if (effectiveTimeoutMs !== null && Date.now() - started >= effectiveTimeoutMs * RETRY_BUDGET_FRACTION) {
             throw err;
         }
         // Signal the caller so it can bump `retryAttempts` (NOT `failureCount`).
@@ -211,8 +221,8 @@ async function chatCompletionReal(config, messages, options) {
         warnVerbose(`[akm] LLM transient failure (${err.code}); retrying once: ${err.message}`);
         const wait = retryBackoffMs();
         await waitForRetry(wait, options?.sleep ?? sleep, options?.signal);
-        // The retry must not exceed the original budget.
-        return await chatCompletionAttempt(config, messages, options, remaining);
+        // The retry spends what is left of the original budget.
+        return await chatCompletionAttempt(config, messages, options, budget);
     }
 }
 // ── Structured-output attempt-then-fallback ─────────────────────────────────
@@ -286,10 +296,8 @@ const RESPONSE_FORMAT_NAMED = /format_ignored|response_format|json_schema/;
  * inline fallback-once when a schema was requested and the provider 4xx's
  * (never retried by the transient-failure policy below, by design — 4xx is
  * a same-request-will-always-fail signal EXCEPT for this one specific,
- * request-shape-dependent case). No cached verdict gates the first attempt:
- * `config.supportsJsonSchema === false` is the only thing that skips it,
- * and that is a value a human (or workflow author) set explicitly, not one
- * a probe wrote automatically.
+ * request-shape-dependent case). Only what a real call this process made has
+ * shown (`isJsonSchemaKnownUnsupported`) skips the first attempt.
  *
  * The thinking-control fields get the same treatment (#1045): a 4xx that
  * names `chat_template_kwargs` or `enable_thinking` is answered by one retry
@@ -298,9 +306,8 @@ const RESPONSE_FORMAT_NAMED = /format_ignored|response_format|json_schema/;
  * same way: the connection stops sending `temperature`, or sends the token cap
  * as `max_completion_tokens`, for the rest of the process.
  */
-async function chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking = (options?.enableThinking ?? config.enableThinking) !== undefined &&
-    !isThinkingControlKnownRejected(config)) {
-    const wantsSchema = Boolean(options?.responseSchema) && config.supportsJsonSchema !== false && !isJsonSchemaKnownUnsupported(config);
+async function chatCompletionAttempt(config, messages, options, budget, includeThinking = sendsThinkingFields(config, options) && !isThinkingControlKnownRejected(config)) {
+    const wantsSchema = Boolean(options?.responseSchema) && !isJsonSchemaKnownUnsupported(config);
     // The schema attempt's error record is held, not emitted: when the retry without the schema
     // recovers the call, that call is ONE success, not a failure plus a success. Every other exit
     // flushes the held record, so a failed call is still recorded once.
@@ -310,12 +317,12 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs, inclu
             emitLlmUsage(held.record);
     };
     try {
-        return await chatCompletionAttemptOnce(config, messages, options, timeoutMs, wantsSchema, includeThinking, held);
+        return await chatCompletionAttemptOnce(config, messages, options, budget(), wantsSchema, includeThinking, held);
     }
     catch (err) {
         // A 5xx that names the response format is answered like the 4xx rejection below (#1150).
         if (wantsSchema && err instanceof LlmCallError && err.namesResponseFormat) {
-            return retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err);
+            return retryWithoutSchema(config, messages, options, budget, includeThinking, err);
         }
         if (!isRejectedRequest(err)) {
             flushHeld();
@@ -326,56 +333,76 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs, inclu
             flushHeld();
             warnVerbose(`[akm] LLM rejected temperature (${err.statusCode}); retrying once without it: ${err.message}`);
             temperatureRejectedConnections.add(key);
-            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+            return chatCompletionAttempt(config, messages, options, budget, includeThinking);
         }
         if (MAX_TOKENS_REPLACED.test(err.message) && !maxCompletionTokensConnections.has(key)) {
             flushHeld();
             warnVerbose(`[akm] LLM rejected max_tokens (${err.statusCode}); retrying once with max_completion_tokens: ${err.message}`);
             maxCompletionTokensConnections.add(key);
-            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+            return chatCompletionAttempt(config, messages, options, budget, includeThinking);
         }
         if (includeThinking && THINKING_FIELD_NAMED.test(err.message)) {
             flushHeld();
             warnVerbose(`[akm] LLM rejected chat_template_kwargs/enable_thinking (${err.statusCode}); retrying once without them: ${err.message}`);
-            const fallback = await chatCompletionAttempt(config, messages, options, timeoutMs, false);
+            const fallback = await chatCompletionAttempt(config, messages, options, budget, false);
             thinkingControlRejectedConnections.add(connectionKey(config));
             return fallback;
         }
         if (!wantsSchema)
             throw err;
-        return retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err);
+        return retryWithoutSchema(config, messages, options, budget, includeThinking, err);
     }
 }
-async function retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err) {
+async function retryWithoutSchema(config, messages, options, budget, includeThinking, err) {
     warnVerbose(`[akm] LLM rejected response_format:json_schema (${err.statusCode}); retrying once without it: ${err.message}`);
-    const fallback = await chatCompletionAttemptOnce(config, messages, options, timeoutMs, false, includeThinking);
+    const fallback = await chatCompletionAttemptOnce(config, messages, options, budget(), false, includeThinking);
     jsonSchemaUnsupportedConnections.add(connectionKey(config));
     return fallback;
 }
+/** Whether this request carries the two thinking-control fields, from a setting or as written. */
+function sendsThinkingFields(config, options) {
+    return ((options?.enableThinking ?? config.inference?.enableThinking) !== undefined ||
+        config.request?.chat_template_kwargs !== undefined ||
+        config.request?.enable_thinking !== undefined);
+}
+/**
+ * The fields of one request: akm's default temperature, the connection's request
+ * fields as written, and the portable settings (the call's own over the
+ * connection's) translated, nearest last. A field the endpoint has rejected on an
+ * earlier call is left out, and the token cap goes by the name it asked for.
+ */
+function requestFields(config, options, includeThinking) {
+    const settings = {
+        ...config.inference,
+        ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+        ...(options?.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+        ...(options?.enableThinking !== undefined ? { enableThinking: options.enableThinking } : {}),
+    };
+    const fields = effectiveRequestFields({ temperature: 0.3, ...config.request }, settings);
+    const key = connectionKey(config);
+    if (temperatureRejectedConnections.has(key))
+        delete fields.temperature;
+    if (!includeThinking) {
+        delete fields.chat_template_kwargs;
+        delete fields.enable_thinking;
+    }
+    if (maxCompletionTokensConnections.has(key) && fields.max_tokens !== undefined) {
+        fields.max_completion_tokens = fields.max_tokens;
+        delete fields.max_tokens;
+    }
+    return fields;
+}
 async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, includeSchema, includeThinking, held) {
-    if (config.extraParams !== undefined) {
-        const issue = validateExtraParams(config.extraParams)[0];
+    if (config.inference?.extraParams !== undefined) {
+        const issue = validateExtraParams(config.inference.extraParams)[0];
         if (issue)
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    // Resolve ONLY a whole-string reference ($VAR/${VAR} or secret://<name>).
-    // The execution boundary normally hands us a materialized credential after
-    // resolving the reference upstream, so re-running the substitution over a
-    // literal key mangled any credential containing `$` — `sk-live$ecret` lost
-    // everything from the `$` onward, and the request failed with an opaque
-    // 401. The narrow check keeps the symbolic form working for any direct
-    // caller that still passes one.
-    const resolvedKey = isApiKeyReference(config.apiKey ?? "")
-        ? resolveSecret(config.apiKey, resolveSecretFromStore)
-        : config.apiKey;
+    const resolvedKey = 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 = includeSchema && options?.responseSchema
         ? {
             response_format: {
@@ -384,32 +411,11 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             },
         }
         : {};
-    // #949: which of these two wire forms a backend honors is a fact about the
-    // backend (and any gateway in front of it), not about akm's own `provider`
-    // label — a llama.cpp build honors chat_template_kwargs, a bare
-    // `enable_thinking` is honored by nothing observed, and a gateway
-    // (freellmapi, Bifrost) can drop either one depending on how it was built.
-    // Send both whenever thinking is explicitly resolved so the same engine
-    // block keeps working across a direct vhost or any gateway in front of it.
-    const resolvedEnableThinking = includeThinking ? (options?.enableThinking ?? config.enableThinking) : undefined;
-    const thinkingParams = resolvedEnableThinking === undefined
-        ? {}
-        : { chat_template_kwargs: { enable_thinking: resolvedEnableThinking }, enable_thinking: resolvedEnableThinking };
-    const reasoningEffortParams = config.reasoningEffort === undefined ? {} : { reasoning_effort: config.reasoningEffort };
-    const key = connectionKey(config);
-    const maxTokensField = maxCompletionTokensConnections.has(key) ? "max_completion_tokens" : "max_tokens";
-    const requestBody = JSON.stringify({
-        model: config.model,
-        messages,
-        ...(temperatureRejectedConnections.has(key)
-            ? {}
-            : { temperature: options?.temperature ?? config.temperature ?? 0.3 }),
-        ...(resolvedMaxTokens !== undefined ? { [maxTokensField]: resolvedMaxTokens } : {}),
-        ...config.extraParams,
-        ...responseFormat,
-        ...thinkingParams,
-        ...reasoningEffortParams,
-    });
+    const fields = requestFields(config, options, includeThinking);
+    const requestBody = JSON.stringify({ ...fields, model: config.model, messages, ...responseFormat });
+    const endpointUrl = openAiOperationUrl(config.endpoint, "chat/completions");
+    // What a message says about the endpoint: never a username or password the URL carries.
+    const shownEndpoint = redactUrlCredentials(config.endpoint);
     // Wall-clock start for per-attempt usage telemetry (#576). Captured here so the
     // emitted duration covers the full request/response/parse cycle of a single
     // attempt, not the retry-wrapping `chatCompletion`.
@@ -423,7 +429,7 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
     try {
         let response;
         try {
-            response = await fetchWithTimeout(config.endpoint, {
+            response = await fetchWithTimeout(endpointUrl, {
                 method: "POST",
                 headers,
                 body: requestBody,
@@ -460,15 +466,15 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
             const status = response.status;
             if (status === 429) {
-                throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
+                throw new LlmCallError(`LLM request rate limited (429) ${shownEndpoint}: ${safeBody}`, "rate_limited", status);
             }
             if (status >= 500 && isHtmlResponse(rawBody)) {
-                throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", status);
+                throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${shownEndpoint}: ${redactSensitiveText(htmlExcerpt(rawBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", status);
             }
             if (status >= 500) {
-                throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status, RESPONSE_FORMAT_NAMED.test(rawBody));
+                throw new LlmCallError(`LLM provider error (${status}) ${shownEndpoint}: ${safeBody}`, "provider_error", status, RESPONSE_FORMAT_NAMED.test(rawBody));
             }
-            throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
+            throw new LlmCallError(`LLM request failed (${status}) ${shownEndpoint}: ${safeBody}`, "provider_error", status);
         }
         // A 2xx response is still an error if the body is HTML where JSON was
         // expected (e.g. a provider serving its web UI). Read the raw body first so
@@ -489,19 +495,19 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             throw err;
         }
         if (isHtmlResponse(rawOkBody)) {
-            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", response.status);
+            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${shownEndpoint}: ${redactSensitiveText(htmlExcerpt(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", response.status);
         }
         let json;
         try {
             json = JSON.parse(rawOkBody);
         }
         catch {
-            throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
+            throw new LlmCallError(`LLM response was not valid JSON ${shownEndpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
         }
         // A 2xx can still carry a provider failure. OpenRouter answers a provider
         // that fails after the headers with a body holding only `error`.
         if (json.error !== undefined && json.error !== null && !json.choices?.length) {
-            throw new LlmCallError(`LLM provider error (${response.status}) ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_error", response.status);
+            throw new LlmCallError(`LLM provider error (${response.status}) ${shownEndpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_error", response.status);
         }
         const responseModel = typeof json.model === "string" && json.model.trim().length > 0 ? json.model : undefined;
         terminalFields = {
@@ -510,8 +516,8 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
             ...extractUsageTokens(json.usage),
         };
-        if (resolvedEnableThinking === false && (terminalFields.reasoningTokens ?? 0) > 0) {
-            warn(`[akm] LLM returned ${terminalFields.reasoningTokens} reasoning tokens despite enableThinking: false; ` +
+        if (fields.enable_thinking === false && (terminalFields.reasoningTokens ?? 0) > 0) {
+            warn(`[akm] LLM returned ${terminalFields.reasoningTokens} reasoning tokens despite thinking being off; ` +
                 'the provider may not honor that control. Configure reasoningEffort: "none" when the provider supports it.');
         }
         const content = (json.choices?.[0]?.message?.content ?? "").trim();
@@ -540,30 +546,6 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
 }
 // ── Availability check ──────────────────────────────────────────────────────
 // ── Reachability probe ──────────────────────────────────────────────────────
-/**
- * Best-effort reachability check with an error message, for setup's optional
- * `--probe` connectivity verification. Deliberately does NOT probe or cache
- * `response_format: json_schema` support: that used to be persisted as
- * `capabilities.structuredOutput` and consulted on every later call, so a
- * config edit that changed the endpoint/model left a stale verdict in place
- * with no invalidation, and a stale `true` sent an unsupported request that
- * the retry policy explicitly does not retry (4xx). `chatCompletion` now
- * attempts the schema request fresh every time and falls back once per call
- * on a 4xx — see the in-memory tracker below.
- */
-export async function probeLlmReachable(config, timeoutMs) {
-    try {
-        const raw = await chatCompletion(config, [{ role: "user", content: "Respond with just the word: ok" }], {
-            maxTokens: 16,
-            temperature: 0,
-            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-        });
-        return raw.length > 0 ? { reachable: true } : { reachable: false, error: "empty response" };
-    }
-    catch (err) {
-        return { reachable: false, error: err instanceof Error ? err.message : String(err) };
-    }
-}
 /**
  * Reachability probe for `akm health` (#914): one GET against the
  * OpenAI-compatible `/models` route, bounded by `timeoutMs`. Any HTTP
@@ -573,7 +555,7 @@ export async function probeLlmReachable(config, timeoutMs) {
  */
 export async function probeLlmEndpoint(config, timeoutMs = 3_000) {
     try {
-        await fetch(`${config.endpoint.replace(/\/+$/, "")}/models`, { signal: AbortSignal.timeout(timeoutMs) });
+        await fetch(openAiOperationUrl(config.endpoint, "models"), { signal: AbortSignal.timeout(timeoutMs) });
         return { reachable: true };
     }
     catch (err) {
@@ -581,16 +563,16 @@ export async function probeLlmEndpoint(config, timeoutMs = 3_000) {
     }
 }
 /**
- * Endpoint-keyed probe memoization (#957): every caller that probes several
- * engine connections in one pass (`akm health`'s engine checks, `akm
- * improve --require-engines`) shares one in-flight probe per distinct
- * endpoint (trailing slashes normalized) instead of firing a duplicate probe
- * when two engines point at the same server. `cache` must be scoped to one
+ * Endpoint-keyed probe memoization (#957): a caller that probes several
+ * connections in one pass (`akm health`'s connections-and-harnesses check)
+ * shares one in-flight probe per distinct endpoint (trailing slashes
+ * normalized) instead of firing a duplicate probe when two connections point
+ * at the same server. `cache` must be scoped to one
  * invocation and never shared across calls — a stale "reachable" surviving
  * past the run that produced it is the failure mode this exists to avoid.
  */
 export function probeEndpointOnce(connection, cache, probe) {
-    const key = connection.endpoint.replace(/\/+$/, "");
+    const key = openAiBaseUrl(connection.endpoint);
     let pending = cache.get(key);
     if (!pending) {
         pending = probe(connection);

package/dist/llm/embedder.js

@@ -3,31 +3,21 @@
 // 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 as isTransformersAvailableReal, LocalEmbedder, } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, LocalEmbedder, LocalRuntimeUnavailableError } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Shared exports ──────────────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
-export { _setTransformersLoaderForTests, DEFAULT_LOCAL_MODEL } from "./embedders/local.js";
+export { _setLocalPipelineLoaderForTests, 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 external Transformers dependency is available.
- * 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 Transformers.js pipeline is
-// expensive to initialise (model download + WASM compilation) and is safe to
-// share across calls because it is stateless once created. Deferring
+// lazily on first use. The loaded model is expensive to initialise (model
+// download, runtime and session load) 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;
@@ -44,11 +34,18 @@ function getLocalEmbedder() {
 export function resetLocalEmbedder() {
     getLocalEmbedder().reset();
 }
+/**
+ * The runtime the local embedder has embedded with in this process, or
+ * `undefined` when it has not loaded a model (nothing was embedded locally).
+ */
+export function localEmbeddingRuntime() {
+    return _localEmbedder?.runtime;
+}
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Generate an embedding for the given text.
  * If embeddingConfig has a remote endpoint, uses the configured OpenAI-compatible endpoint.
- * Otherwise falls back to local Transformers.js using the model from
+ * Otherwise falls back to the local embedder using the model from
  * `embeddingConfig.localModel` or `DEFAULT_LOCAL_MODEL`.
  *
  * Results are cached in an LRU cache (max ~100 entries) keyed by query text
@@ -98,8 +95,8 @@ async function embedOnce(text, embeddingConfig, signal) {
  * sub-batch or oversized document that fails is skipped rather than
  * aborting the whole call — pass `onSkip` to learn which indices were
  * skipped and why; the result array holds `undefined` at those indices.
- * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
- * which processes texts in chunks of 32 for genuine batched inference.
+ * Uses the LocalEmbedder.embedBatch path for the local model, which processes
+ * texts in chunks of 32 for genuine batched inference.
  *
  * `onBatch`, when given, fires once per provider/local batch as it completes
  * (#954) so a caller can commit each batch's rows durably as they land
@@ -123,7 +120,7 @@ export async function embedBatch(texts, embeddingConfig, signal, onSkip, onBatch
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal, onSkip, onBatch);
     }
-    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // Local model: use the batched path (chunks of 32 via LocalEmbedder).
     // When a localModel override is set we cannot share the singleton (which uses
     // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
@@ -144,7 +141,7 @@ export async function embedBatch(texts, embeddingConfig, signal, onSkip, onBatch
 // ── Similarity ──────────────────────────────────────────────────────────────
 // `cosineSimilarity` was moved to `./embedders/types.ts` so importers
 // (notably `db.ts`) can pull the math function without dragging in this
-// module and its Transformers.js import chain.
+// module and the local embedder's import chain.
 export { cosineSimilarity } from "./embedders/types.js";
 // ── Model ID resolution ─────────────────────────────────────────────────────
 /**
@@ -154,7 +151,7 @@ export { cosineSimilarity } from "./embedders/types.js";
  *
  * Rules:
  *   - Remote endpoint: use `config.model` (the API-level model name).
- *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - Local model: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
  *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
  */
 export function resolveEmbeddingModelId(embeddingConfig) {
@@ -193,14 +190,6 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
             };
         }
     }
-    // Check if the package is importable before attempting the model download.
-    if (!isTransformersAvailable()) {
-        return {
-            available: false,
-            reason: "missing-package",
-            message: "The @huggingface/transformers dependency is unavailable.",
-        };
-    }
     try {
         await getLocalEmbedder().getPipeline(embeddingConfig?.localModel);
         return { available: true };
@@ -208,12 +197,8 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
     catch (err) {
         return {
             available: false,
-            reason: "model-download-failed",
+            reason: err instanceof LocalRuntimeUnavailableError ? "runtime-unavailable" : "model-download-failed",
             message: err instanceof Error ? err.message : String(err),
         };
     }
 }
-export async function isEmbeddingAvailable(embeddingConfig) {
-    const result = await checkEmbeddingAvailability(embeddingConfig);
-    return result.available;
-}

package/dist/llm/embedders/connection.js

@@ -0,0 +1,31 @@
+// 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 { defaultConnection } from "../../core/config/config.js";
+import { apiKeyReference } from "../../core/config/credentials.js";
+import { openAiBaseUrl } from "../../core/endpoint-url.js";
+import { warnOnce } from "../../core/warn.js";
+/**
+ * The embedding block as the embedder uses it. `embedding.model` without an
+ * `embedding.endpoint` means the model is served by the default connection: its
+ * endpoint, and its key (its `$VAR`, else `credentials.json` under its name).
+ * With no default connection there is nothing to serve it, so the built-in local
+ * embedder runs, with one warning. Computed where the embedder is used and never
+ * stored, so a config write cannot persist it.
+ */
+export function effectiveEmbedding(config) {
+    const embedding = config.embedding;
+    if (!embedding || embedding.endpoint !== undefined || !embedding.model)
+        return embedding;
+    const found = defaultConnection(config);
+    if (!found) {
+        warnOnce("embedding:no-default-connection", "embedding.model is set, but there is no embedding.endpoint and no default connection to serve it; using the built-in local embedder. Add a connection with `akm setup`.");
+        return embedding;
+    }
+    return {
+        ...embedding,
+        endpoint: openAiBaseUrl(found.connection.endpoint),
+        ...(apiKeyReference(found.connection.apiKey) !== undefined ? { apiKey: found.connection.apiKey } : {}),
+        credentialName: found.name,
+    };
+}

package/dist/llm/embedders/local-model-files.js

@@ -0,0 +1,56 @@
+// 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/.
+/**
+ * The files of a local embedding model, fetched from the Hugging Face Hub into
+ * akm's model cache on first use. The layout is `<HF_HOME>/<repo>/<file>` (HF_HOME
+ * defaults to `<akm cache>/models`), the one earlier releases wrote through
+ * Transformers.js, so a cache they filled is reused as it is.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../../core/common.js";
+import { getCacheDir } from "../../core/paths.js";
+import { writeResponseToFileCapped } from "../../runtime.js";
+/** `config.json` is not read here; releases that ran the model through Transformers.js require it, so it stays in the cache. */
+const MODEL_FILES = ["tokenizer.json", "tokenizer_config.json", "config.json", "onnx/model.onnx"];
+function isEnabledEnvironmentFlag(value) {
+    return /^(?:1|true|yes|on)$/i.test(value?.trim() ?? "");
+}
+async function downloadFile(url, target) {
+    const response = await fetchWithRetry(url, undefined, { timeout: 60_000 });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error(`Could not download ${url}: HTTP ${response.status}`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const partial = `${target}.${process.pid}.tmp`;
+    try {
+        // No overall deadline for a 127 MB file on a slow link (Transformers.js had none): only 60 s without bytes fails it.
+        await writeResponseToFileCapped(partial, response, { stallTimeoutMs: 60_000 });
+        fs.renameSync(partial, target);
+    }
+    catch (error) {
+        fs.rmSync(partial, { force: true });
+        throw error;
+    }
+}
+/**
+ * Make sure every file of `modelName` (a Hub repo id) is cached and return the
+ * directory holding them. With `HF_HUB_OFFLINE` set nothing is fetched and a
+ * missing file is an error.
+ */
+export async function ensureLocalModelFiles(modelName) {
+    const modelDir = path.join(process.env.HF_HOME || path.join(getCacheDir(), "models"), ...modelName.split("/"));
+    const offline = isEnabledEnvironmentFlag(process.env.HF_HUB_OFFLINE);
+    for (const file of MODEL_FILES) {
+        const target = path.join(modelDir, ...file.split("/"));
+        if (fs.existsSync(target))
+            continue;
+        if (offline) {
+            throw new Error(`The local embedding model file ${target} is not cached and HF_HUB_OFFLINE is set.`);
+        }
+        await downloadFile(`https://huggingface.co/${modelName}/resolve/main/${file}`, target);
+    }
+    return modelDir;
+}