akm-cli 0.10.261014-beta → 0.10.261015-beta

package/dist/llm/embedders/onnx-runtime.js

@@ -0,0 +1,121 @@
+// 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/.
+/**
+ * ONNX Runtime for the local embedder: onnxruntime-node's N-API binding and the
+ * library it links, kept in akm's cache and loaded from there. `akm setup`
+ * fetches them when local embeddings are chosen, and the first local embedding
+ * fetches them when setup did not.
+ *
+ * akm does not depend on the onnxruntime-node package. Its JavaScript loads the
+ * binding from a path inside the package, which a compiled standalone binary can
+ * only satisfy by writing an embedded copy to the temp directory, and its install
+ * script downloads CUDA providers akm never uses. Here the binding is loaded by
+ * absolute path with the library beside it in the same folder, where the system
+ * loader finds it (`$ORIGIN` on Linux, `@loader_path` on macOS).
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { toErrorMessage } from "../../core/common.js";
+import { fetchNpmPackageFiles, NPM_REGISTRY } from "../../core/npm-package.js";
+import { getCacheDir } from "../../core/paths.js";
+import { info } from "../../core/warn.js";
+/**
+ * The onnxruntime-node release whose binding akm loads, and the only one it supports. akm calls the binding through
+ * the contract between that package's own JavaScript and its addon, which no release documents or promises and which
+ * moves between releases (after 1.24.3, `loadModel` returns a promise and `initOrtOnce` takes a third argument). What
+ * akm relies on: `initOrtOnce(logLevel, Tensor)`; `new InferenceSession()`; `loadModel(path, options)`;
+ * `inputMetadata` and `outputMetadata` (`{ name }[]`); `run(feeds, fetches)`, which reads a tensor as
+ * `{ type, data, dims, location }` and makes each result with `new Tensor(type, data, dims)`. To move it: change this
+ * version, check that contract in the new release's `lib/binding.ts` and `lib/backend.ts`, check the library names in
+ * {@link LIBRARIES}, and run the reference-vector test in `tests/integration/semantic-search-e2e.test.ts`, the gate for
+ * any bump.
+ */
+export const ONNXRUNTIME_VERSION = "1.24.3";
+/**
+ * The platforms akm offers local embeddings on, each with the library the binding links there. Every other platform
+ * has keyword search and remote embeddings. A platform is listed once a real run has verified it; Linux means glibc.
+ */
+const LIBRARIES = {
+    "linux-x64": "libonnxruntime.so.1",
+    "darwin-arm64": `libonnxruntime.${ONNXRUNTIME_VERSION}.dylib`,
+};
+const BINDING = "onnxruntime_binding.node";
+/** This machine as `<platform>-<arch>`, Linux without glibc as `linux-musl-<arch>`. */
+function thisPlatform() {
+    const header = process.report?.getReport()?.header;
+    const musl = process.platform === "linux" && !header?.glibcVersionRuntime;
+    return `${process.platform}${musl ? "-musl" : ""}-${process.arch}`;
+}
+/** Whether akm offers local embeddings on this machine. */
+export function hasLocalEmbeddings() {
+    return thisPlatform() in LIBRARIES;
+}
+/** What a machine without local embeddings is told, wherever it is told. */
+export function noLocalEmbeddingsReason() {
+    return `Local embeddings are not available on ${thisPlatform()}; choose a remote endpoint or keyword search.`;
+}
+/** A tensor as the binding reads one and makes its results. */
+export class OnnxTensor {
+    type;
+    data;
+    dims;
+    location = "cpu";
+    constructor(type, data, dims) {
+        this.type = type;
+        this.data = data;
+        this.dims = dims;
+    }
+}
+/** Fetch the binding and its library into `directory`, naming the package, its URL and the folder when it cannot. */
+async function fetchOnnxRuntime(directory) {
+    const library = LIBRARIES[thisPlatform()];
+    if (!library)
+        throw new Error(noLocalEmbeddingsReason());
+    const source = `bin/napi-v6/${process.platform}/${process.arch}`;
+    try {
+        info(`Fetching ONNX Runtime ${ONNXRUNTIME_VERSION} for local embeddings (about 86 MB, once) into ${directory}.`);
+        // The library first: a binding in the folder means its library is there too.
+        await fetchNpmPackageFiles("onnxruntime-node", ONNXRUNTIME_VERSION, directory, [
+            { member: `package/${source}/${library}`, file: library },
+            { member: `package/${source}/${BINDING}`, file: BINDING },
+        ]);
+        return directory;
+    }
+    catch (error) {
+        throw new Error(`Could not fetch ONNX Runtime ${ONNXRUNTIME_VERSION} for local embeddings: package onnxruntime-node from ${NPM_REGISTRY}/onnxruntime-node/${ONNXRUNTIME_VERSION} into ${directory}: ${toErrorMessage(error)}. ` +
+            `Run \`akm setup --yes\` with network access, or copy ${BINDING} and ${library} from that package's ${source}/ into that folder.`);
+    }
+}
+/**
+ * The binding, loaded and initialised from `<cache>/onnxruntime/<version>-<platform>-<arch>/`, where it and its library
+ * are fetched first when the binding is not there.
+ */
+async function loadBinding() {
+    const directory = path.join(getCacheDir(), "onnxruntime", `${ONNXRUNTIME_VERSION}-${thisPlatform()}`);
+    if (!fs.existsSync(path.join(directory, BINDING)))
+        await fetchOnnxRuntime(directory);
+    const loaded = createRequire(import.meta.url)(path.join(directory, BINDING));
+    // 3: errors only.
+    loaded.initOrtOnce(3, OnnxTensor);
+    return loaded;
+}
+/** Once per process, however many callers ask meanwhile; a failure is not kept, so the next caller tries again. */
+let loading;
+/** The runtime, ready to load models: fetched first when it is not in the cache, then loaded. */
+export async function loadOnnxRuntime() {
+    loading ??= loadBinding().catch((error) => {
+        loading = undefined;
+        throw error;
+    });
+    const loaded = await loading;
+    return {
+        createSession(modelPath) {
+            const session = new loaded.InferenceSession();
+            session.loadModel(modelPath, { executionProviders: ["cpu"], logSeverityLevel: 3 });
+            const outputs = Object.fromEntries(session.outputMetadata.map(({ name }) => [name, null]));
+            return { inputNames: session.inputMetadata.map(({ name }) => name), run: (feeds) => session.run(feeds, outputs) };
+        },
+    };
+}

package/dist/scripts/akm-migrate-node.js

@@ -8260,22 +8260,11 @@ function loadBunSqlite() {
   }
   return bunSqliteModule;
 }
-function abiMismatchRemedy(message) {
-  const ABI_MISMATCH_SHAPES = [
-    "did not self-register",
-    "NODE_MODULE_VERSION",
-    "was compiled against a different",
-    "invalid ELF header"
-  ];
-  if (!ABI_MISMATCH_SHAPES.some((shape) => message.includes(shape)))
-    return;
-  return `akm could not load 'better-sqlite3': its native binding was built for a different
-` + `Node.js version than the one now running (this Node is ABI ${process.versions.modules}).
-` + `This is what happens when Node is upgraded after akm is installed. It is NOT a
-` + `broken install, and reinstalling akm is not required.
-` + `  Fix: npm rebuild better-sqlite3        # in akm's install directory
-` + `  Or:  npm install -g akm-cli            # reinstall, rebuilding against this Node
-` + "  Or:  run akm under Bun, whose built-in SQLite driver needs no native binding.";
+function missingBindingRemedy() {
+  return `akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.
+` + `  • Its package carries prebuilt bindings for Linux and macOS on x64 and arm64 and for
+` + `    Windows on x64 and arm64; this machine is ${process.platform} ${process.arch}.
+` + "  • Reinstall akm (`npm install -g akm-cli`) if the package is missing (a global\n" + "    `npm i -g better-sqlite3` will NOT be resolved — Node loads it from akm's own node_modules).\n" + "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native binding.";
 }
 function loadBetterSqlite3() {
   if (!betterSqlite3Ctor) {
@@ -8284,7 +8273,7 @@ function loadBetterSqlite3() {
       mod = nodeRequire2("better-sqlite3");
     } catch (err) {
       const raw = err instanceof Error ? err.message : String(err);
-      throw new Error(`${abiMismatchRemedy(raw) ?? MISSING_BINDING_REMEDY}
+      throw new Error(`${missingBindingRemedy()}
   Underlying load error: ${raw}`);
     }
     betterSqlite3Ctor = mod.default ?? mod;
@@ -8303,10 +8292,9 @@ function openNodeDatabase(path8, opts) {
     db = opts ? new BetterSqlite3(path8, options) : new BetterSqlite3(path8);
   } catch (err) {
     const raw = err instanceof Error ? err.message : String(err);
-    const remedy = abiMismatchRemedy(raw);
-    if (!remedy)
+    if (!raw.includes("better_sqlite3.node"))
       throw err;
-    throw new Error(`${remedy}
+    throw new Error(`${missingBindingRemedy()}
   Underlying error: ${raw}`);
   }
   return {
@@ -8321,14 +8309,10 @@ function openNodeDatabase(path8, opts) {
     close: db.close.bind(db)
   };
 }
-var isBun2, nodeRequire2, bunSqliteModule, betterSqlite3Ctor, MISSING_BINDING_REMEDY;
+var isBun2, nodeRequire2, bunSqliteModule, betterSqlite3Ctor;
 var init_database = __esm(() => {
   isBun2 = !!process.versions?.bun;
   nodeRequire2 = createRequire3(import.meta.url);
-  MISSING_BINDING_REMEDY = `akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.
-` + `  • Reinstall akm with a working C/C++ build toolchain so its optional
-` + "    'better-sqlite3' native binding builds (a global `npm i -g better-sqlite3`\n" + `    will NOT be resolved — Node loads it from akm's own node_modules).
-` + "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native build.";
 });
 
 // src/core/time.ts
@@ -55583,11 +55567,12 @@ init_session_log_v2();
 
 // src/integrations/harnesses/opencode/runtime/binary.ts
 init_common();
-init_paths();
-init_warn();
+
+// src/core/npm-package.ts
 init_runtime();
+init_common();
 
-// src/integrations/harnesses/opencode/runtime/tar.ts
+// src/core/tar.ts
 class ByteReader {
   #chunks;
   #pending = Buffer.alloc(0);
@@ -55627,6 +55612,8 @@ class ByteReader {
 }
 
 // src/integrations/harnesses/opencode/runtime/binary.ts
+init_paths();
+init_warn();
 var PACKAGES = new Set([
   "@opencode/cli-linux-x64",
   "@opencode/cli-linux-x64-baseline",

package/dist/scripts/akm-migrate.js

@@ -8259,22 +8259,11 @@ function loadBunSqlite() {
   }
   return bunSqliteModule;
 }
-function abiMismatchRemedy(message) {
-  const ABI_MISMATCH_SHAPES = [
-    "did not self-register",
-    "NODE_MODULE_VERSION",
-    "was compiled against a different",
-    "invalid ELF header"
-  ];
-  if (!ABI_MISMATCH_SHAPES.some((shape) => message.includes(shape)))
-    return;
-  return `akm could not load 'better-sqlite3': its native binding was built for a different
-` + `Node.js version than the one now running (this Node is ABI ${process.versions.modules}).
-` + `This is what happens when Node is upgraded after akm is installed. It is NOT a
-` + `broken install, and reinstalling akm is not required.
-` + `  Fix: npm rebuild better-sqlite3        # in akm's install directory
-` + `  Or:  npm install -g akm-cli            # reinstall, rebuilding against this Node
-` + "  Or:  run akm under Bun, whose built-in SQLite driver needs no native binding.";
+function missingBindingRemedy() {
+  return `akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.
+` + `  \u2022 Its package carries prebuilt bindings for Linux and macOS on x64 and arm64 and for
+` + `    Windows on x64 and arm64; this machine is ${process.platform} ${process.arch}.
+` + "  \u2022 Reinstall akm (`npm install -g akm-cli`) if the package is missing (a global\n" + "    `npm i -g better-sqlite3` will NOT be resolved \u2014 Node loads it from akm's own node_modules).\n" + "  \u2022 Or run akm under Bun, which has a built-in SQLite driver and needs no native binding.";
 }
 function loadBetterSqlite3() {
   if (!betterSqlite3Ctor) {
@@ -8283,7 +8272,7 @@ function loadBetterSqlite3() {
       mod = nodeRequire2("better-sqlite3");
     } catch (err) {
       const raw = err instanceof Error ? err.message : String(err);
-      throw new Error(`${abiMismatchRemedy(raw) ?? MISSING_BINDING_REMEDY}
+      throw new Error(`${missingBindingRemedy()}
   Underlying load error: ${raw}`);
     }
     betterSqlite3Ctor = mod.default ?? mod;
@@ -8302,10 +8291,9 @@ function openNodeDatabase(path8, opts) {
     db = opts ? new BetterSqlite3(path8, options) : new BetterSqlite3(path8);
   } catch (err) {
     const raw = err instanceof Error ? err.message : String(err);
-    const remedy = abiMismatchRemedy(raw);
-    if (!remedy)
+    if (!raw.includes("better_sqlite3.node"))
       throw err;
-    throw new Error(`${remedy}
+    throw new Error(`${missingBindingRemedy()}
   Underlying error: ${raw}`);
   }
   return {
@@ -8320,14 +8308,10 @@ function openNodeDatabase(path8, opts) {
     close: db.close.bind(db)
   };
 }
-var isBun2, nodeRequire2, bunSqliteModule, betterSqlite3Ctor, MISSING_BINDING_REMEDY;
+var isBun2, nodeRequire2, bunSqliteModule, betterSqlite3Ctor;
 var init_database = __esm(() => {
   isBun2 = !!process.versions?.bun;
   nodeRequire2 = createRequire2(import.meta.url);
-  MISSING_BINDING_REMEDY = `akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.
-` + `  \u2022 Reinstall akm with a working C/C++ build toolchain so its optional
-` + "    'better-sqlite3' native binding builds (a global `npm i -g better-sqlite3`\n" + `    will NOT be resolved \u2014 Node loads it from akm's own node_modules).
-` + "  \u2022 Or run akm under Bun, which has a built-in SQLite driver and needs no native build.";
 });
 
 // src/core/time.ts
@@ -55581,11 +55565,12 @@ init_session_log_v2();
 
 // src/integrations/harnesses/opencode/runtime/binary.ts
 init_common();
-init_paths();
-init_warn();
+
+// src/core/npm-package.ts
 init_runtime();
+init_common();
 
-// src/integrations/harnesses/opencode/runtime/tar.ts
+// src/core/tar.ts
 class ByteReader {
   #chunks;
   #pending = Buffer.alloc(0);
@@ -55625,6 +55610,8 @@ class ByteReader {
 }
 
 // src/integrations/harnesses/opencode/runtime/binary.ts
+init_paths();
+init_warn();
 var PACKAGES = new Set([
   "@opencode/cli-linux-x64",
   "@opencode/cli-linux-x64-baseline",

package/dist/setup/semantic-assets.js

@@ -2,14 +2,16 @@
 // 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/.
 /**
- * Semantic-search asset preparation for the setup wizard. The embedding
- * runtime (onnxruntime-node) is a normal package dependency; setup never
- * mutates the installed CLI. This module only prepares the model.
+ * Semantic-search asset preparation for setup. For the built-in local embedder
+ * that is its runtime (onnxruntime-node's binding and library) and its model,
+ * both fetched into akm's cache; for an embedding endpoint, a check that it
+ * answers.
  */
 import * as p from "../cli/clack.js";
 import { isHttpUrl } from "../core/common.js";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL } from "../llm/embedder.js";
 import { effectiveEmbedding } from "../llm/embedders/connection.js";
+import { ONNXRUNTIME_VERSION } from "../llm/embedders/onnx-runtime.js";
 // Approximate first-download size of the default local model (DEFAULT_LOCAL_MODEL), used in the setup note.
 const LOCAL_MODEL_APPROX_SIZE_MB = 127;
 export function isRemoteEmbeddingConfig(embedding) {
@@ -23,7 +25,8 @@ export function describeSemanticSearchAssets(embedding) {
         return [`• Embedding endpoint: ${embedding?.provider ?? "custom"} / ${embedding?.model} (no local model download)`];
     }
     return [
-        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download on first use)`,
+        `• ONNX Runtime ${ONNXRUNTIME_VERSION}, the local embedder's runtime (~86 MB download, once)`,
+        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download, once)`,
     ];
 }
 export async function prepareSemanticSearchAssets(config) {
@@ -32,7 +35,7 @@ export async function prepareSemanticSearchAssets(config) {
     const spin = p.spinner();
     spin.start(remote
         ? "Checking remote embedding endpoint..."
-        : `Downloading local embedding model (${embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
+        : `Downloading the local embedder's runtime and model (${embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
     const result = await checkEmbeddingAvailability(embedding);
     if (!result.available) {
         spin.stop("Semantic-search assets could not be prepared.");
@@ -50,6 +53,6 @@ export async function prepareSemanticSearchAssets(config) {
             return { ok: false, reason: "local-model-download", message: result.message };
         }
     }
-    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
+    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedder's runtime and model downloaded and ready.");
     return { ok: true };
 }

package/dist/setup/setup.js

@@ -19,7 +19,9 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import * as p from "../cli/clack.js";
 import { akmInit } from "../commands/sources/init.js";
+import { targetRows } from "../commands/targets.js";
 import { deriveBundleIds } from "../core/bundle-id.js";
+import { toErrorMessage } from "../core/common.js";
 import { bundleEntryToSourceEntry, DEFAULT_CONFIG, defaultConnection, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
 import { readConfigText } from "../core/config/config-io.js";
 import { listTopLevelConfigKeys } from "../core/config/config-schema.js";
@@ -30,6 +32,8 @@ import { getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core
 import { warn, warnOnce } from "../core/warn.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { readLockfile } from "../integrations/lockfile.js";
+import { checkEmbeddingAvailability } from "../llm/embedder.js";
+import { effectiveEmbedding } from "../llm/embedders/connection.js";
 import { detectEnvironment, renderDetectionSummary } from "./detect.js";
 import { bail, prompt } from "./prompt.js";
 import { prepareSemanticSearchAssets } from "./semantic-assets.js";
@@ -305,6 +309,50 @@ function finalizeSetupDraft(draft) {
         delete finalized.defaultBundle;
     return finalized;
 }
+/** Where a process of `config` runs, as `akm info` and `akm health` say it. */
+function processRow(config, process) {
+    return targetRows({ config }).find((row) => row.type === "process" && row.process === process);
+}
+/**
+ * What `--yes` and `--from` do for local embeddings once the config is saved: fetch the local embedder's runtime and
+ * model and load them. Undefined when the saved config does not embed locally.
+ */
+async function prepareLocalEmbeddings(config, noProbe) {
+    if (processRow(config, "embedding")?.kind !== "local")
+        return undefined;
+    if (noProbe)
+        return "skipped";
+    const result = await checkEmbeddingAvailability(effectiveEmbedding(config));
+    if (result.available)
+        return "ready";
+    warn(`[akm setup] Semantic search is blocked: ${result.message}`);
+    return `blocked: ${result.message}`;
+}
+/** The wizard's offer to fetch what akm's own agent runtime runs, when the saved config runs agent work there. */
+async function offerAgentRuntimeFetch(config) {
+    if (processRow(config, "agents")?.kind !== "connection")
+        return;
+    const { agentRuntime } = await import("../integrations/agent/runtime.js");
+    const pending = agentRuntime.pendingFetch();
+    if (pending === undefined)
+        return;
+    const fetchNow = await prompt(() => p.confirm({
+        message: `Agent work runs on akm's own runtime. Fetch ${pending} for it now, rather than on the first agent run?`,
+        initialValue: true,
+    }));
+    if (!fetchNow)
+        return;
+    const spin = p.spinner();
+    spin.start(`Fetching ${pending}...`);
+    try {
+        await agentRuntime.fetch();
+        spin.stop("akm's own agent runtime is ready.");
+    }
+    catch (error) {
+        spin.stop("akm's own agent runtime could not be fetched.");
+        p.log.warn(`${toErrorMessage(error)}\nThe first agent run tries again.`);
+    }
+}
 const NOTHING_DETECTED = {
     harnesses: [],
     localServers: [],
@@ -538,6 +586,8 @@ export async function runSetupWizard(opts) {
     // Non-interactive setup paths never reach this interactive-only step.
     p.log.step("Scheduled Tasks");
     await stepScheduledTasks();
+    if (opts?.noProbe !== true)
+        await offerAgentRuntimeFetch(savedConfig);
     if (semanticSearchMode.mode === "auto") {
         if (semanticSearchMode.prepareAssets) {
             const ready = await prepareSemanticSearchAssets(savedConfig);
@@ -624,12 +674,13 @@ export async function runSetupWithDefaults(opts) {
     const { config, credentials } = await applyNonInteractiveDefaults(current, stashDir, opts);
     const finalConfig = finalizeSetupDraft(config);
     validateCompleteConfig(finalConfig);
-    const { precommit: initResult } = await saveSetupConfig(current, finalConfig, async () => {
+    const { config: savedConfig, precommit: initResult } = await saveSetupConfig(current, finalConfig, async () => {
         storeCredentials(credentials);
         if (opts.noInit)
             return undefined;
         return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
     });
+    const semanticAssets = await prepareLocalEmbeddings(savedConfig, opts.noProbe);
     return {
         configPath: getConfigPath(),
         bundleDir: stashDir,
@@ -637,6 +688,7 @@ export async function runSetupWithDefaults(opts) {
         written: true,
         fields: Object.keys(finalConfig).filter((k) => finalConfig[k] !== undefined),
         runs: describeRuns(finalConfig),
+        ...(semanticAssets ? { semanticAssets } : {}),
     };
 }
 /**
@@ -736,12 +788,13 @@ export async function runSetupFromConfig(opts) {
     const finalizedMerged = finalizeSetupDraft(merged);
     // Reject an invalid merged config before touching the stash.
     validateCompleteConfig(finalizedMerged);
-    const { precommit: initResult } = await saveSetupConfig(current, finalizedMerged, async () => {
+    const { config: savedConfig, precommit: initResult } = await saveSetupConfig(current, finalizedMerged, async () => {
         storeCredentials(credentials);
         if (opts.noInit)
             return undefined;
         return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
     });
+    const semanticAssets = await prepareLocalEmbeddings(savedConfig, opts.noProbe);
     return {
         configPath: getConfigPath(),
         bundleDir: stashDir,
@@ -749,6 +802,7 @@ export async function runSetupFromConfig(opts) {
         written: true,
         fields: Object.keys(incoming).filter((k) => incoming[k] !== undefined),
         runs: describeRuns(finalizedMerged),
+        ...(semanticAssets ? { semanticAssets } : {}),
     };
 }
 // ── Setup --from <file> bootstrap helper ────────────────────────────────────

package/dist/setup/steps/embeddings.js

@@ -3,7 +3,10 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Setup step 4: embeddings. A model the connection serves, akm's built-in local
- * embedder, another endpoint, or off (which is semantic search off).
+ * embedder, another endpoint, or off (which is semantic search off). The local
+ * embedder is offered only where akm has local embeddings
+ * (`llm/embedders/onnx-runtime.ts`); everywhere else the choice is an endpoint
+ * or keyword search.
  */
 import * as p from "../../cli/clack.js";
 import { defaultConnection, } from "../../core/config/config.js";
@@ -11,6 +14,7 @@ import { apiKeyReference, resolveApiKey, storedCredential } from "../../core/con
 import { sameEndpoint } from "../../core/endpoint-url.js";
 import { UsageError } from "../../core/errors.js";
 import { redactUrlCredentials } from "../../core/redaction.js";
+import { hasLocalEmbeddings, noLocalEmbeddingsReason } from "../../llm/embedders/onnx-runtime.js";
 import { isEmbeddingModel } from "../../llm/model-list.js";
 import { prompt } from "../prompt.js";
 import { describeSemanticSearchAssets, isRemoteEmbeddingConfig } from "../semantic-assets.js";
@@ -45,6 +49,10 @@ function warnOfDroppedKey(current, endpoint, keyGiven, interactive) {
 }
 function fromFlags(input) {
     const { flags } = input;
+    if (flags.embedding === "local" && !hasLocalEmbeddings()) {
+        warnUser(`${noLocalEmbeddingsReason()} --embedding local is ignored: semantic search stays off.`, false);
+        return { kind: "off" };
+    }
     if (flags.embedding === "off" || flags.embedding === "local")
         return { kind: flags.embedding };
     const model = flags.embedding;
@@ -81,9 +89,12 @@ async function askSource(input) {
     const hasServing = servingConnection(input) !== undefined;
     const heldModel = hasServing && current.embedding?.endpoint === undefined ? current.embedding?.model : undefined;
     const connectionModels = [...new Set([...(heldModel ? [heldModel] : []), ...served])];
+    const local = hasLocalEmbeddings();
+    if (!local)
+        p.log.info(noLocalEmbeddingsReason());
     const options = [
         ...connectionModels.map((model) => ({ value: `model:${model}`, label: model, hint: "served by the connection" })),
-        { value: "local", label: "Built-in local embedder", hint: "no server needed" },
+        ...(local ? [{ value: "local", label: "Built-in local embedder", hint: "no server needed" }] : []),
         { value: "endpoint", label: "Another endpoint" },
         { value: "off", label: "Off", hint: "keyword search only" },
     ];
@@ -93,7 +104,9 @@ async function askSource(input) {
             ? `model:${heldModel}`
             : served[0]
                 ? `model:${served[0]}`
-                : "local";
+                : local
+                    ? "local"
+                    : "off";
     const choice = await prompt(() => p.select({ message: "Which embedding source should akm use?", options, initialValue }));
     if (choice === "local" || choice === "off")
         return { kind: choice };
@@ -104,7 +117,7 @@ async function askSource(input) {
         ...(current.embedding?.endpoint ? { initialValue: current.embedding.endpoint } : {}),
     });
     if (endpoint === undefined)
-        return { kind: "local" };
+        return { kind: local ? "local" : "off" };
     // A key belongs to the endpoint it was given for, so the current one is offered for that endpoint alone.
     const unchangedEndpoint = current.embedding?.endpoint !== undefined && sameEndpoint(current.embedding.endpoint, endpoint);
     const held = unchangedEndpoint
@@ -141,6 +154,10 @@ export async function stepEmbeddings(input) {
         return { answer, semantic: { mode: "off", prepareAssets: false } };
     const after = embeddingAfter(input, answer);
     p.note(describeSemanticSearchAssets(after).join("\n"), "Semantic Search Assets");
+    if (!input.probe) {
+        p.log.info("Offline run: semantic search is not checked or prepared now; the first `akm index` does both.");
+        return { answer, semantic: { mode: "auto", prepareAssets: false } };
+    }
     const prepareAssets = await prompt(() => p.confirm({
         message: isRemoteEmbeddingConfig(after)
             ? "Check the embedding endpoint and verify semantic search now?"