@oar-sh/oar 0.9.22 → 0.9.24

package/server/services/model-variant-catalog-service.mjs

@@ -28,7 +28,13 @@
 //   * curated ids only seed an EMPTY catalog; once an authoritative snapshot
 //     (a running engine or the server-side discovery) has listed the models,
 //     anything absent from it is marked `unavailable` (enabled rows stay
-//     listed so a picker can show them greyed; disabled ones are pruned).
+//     listed so a picker can show them greyed; disabled ones are pruned);
+//   * with a model map (`copilot_model_state`, provider-model-state.mjs) a row
+//     seen for the first time starts as the user would expect: off when the
+//     user turned that row off before (a pruned row is remembered), like the
+//     model's other rows for a new effort level, and as the "Turn new models
+//     on automatically" switch says for a whole new model, which is also
+//     flagged new. Without one (tests, older wiring) new rows start off.
 import { humanizeModelLabel } from '../public/app/model-selector-options.mjs';
 import { latestModelCatalogRefresh } from '../../shared/model-catalog-freshness.mjs';
 import {
@@ -39,6 +45,7 @@ import {
 import { KNOWN_REASONING_EFFORTS, MODEL_PICKER_CATEGORIES } from '../../shared/model-descriptors.mjs';
 import { copilotCatalogIndexByModel, inferCopilotVendor } from '../../shared/copilot-model-order.mjs';
 import { selectModelIdsForVariantRefresh } from '../../shared/model-refresh.mjs';
+import { decideNewCopilotVariant, migrateCopilotModelState } from './provider-model-state.mjs';
 
 export const SUPPORTED_REASONING_EFFORTS = [...KNOWN_REASONING_EFFORTS];
 /**
@@ -471,6 +478,14 @@ export function createModelVariantCatalogService({
   autoModelSentinel = 'auto',
   // (args: string[]) => Promise<string>; the `copilot help` text fallback.
   runCopilotCliCommand = async () => '',
+  // { readCopilot(), writeCopilot(state) } (provider-model-state.mjs); null
+  // keeps the old rule: every new row starts off.
+  modelStateStore = null,
+  // (baseModelIds, on) — whole new models were added (the toast).
+  onNewModels = () => {},
+  // ({ source }) — a snapshot that read the runtime's real list arrived
+  // (counts as a Copilot model refresh).
+  onAuthoritativeSnapshot = () => {},
 } = {}) {
   const DEFAULT_MODEL = String(defaultModel || 'gpt-5.4-mini').trim() || 'gpt-5.4-mini';
   const AUTO_MODEL_SENTINEL = String(autoModelSentinel || 'auto');
@@ -511,6 +526,56 @@ export function createModelVariantCatalogService({
     return modelSelectorSql.listEnabledVariants.all().map((row) => normalizeModelVariantRow(row)).sort(compareVariantRows);
   }
 
+  /**
+   * The Copilot model map, built from the table the first time (every model
+   * there known, every disabled row remembered as off). Null without a store.
+   */
+  function loadCopilotModelState(rows = null) {
+    if (!modelStateStore) return null;
+    try {
+      const stored = modelStateStore.readCopilot();
+      if (stored) return stored;
+      const migrated = migrateCopilotModelState(rows || listModelVariantRows());
+      modelStateStore.writeCopilot(migrated);
+      return migrated;
+    } catch {
+      return null;
+    }
+  }
+
+  function saveCopilotModelState(state) {
+    try {
+      modelStateStore?.writeCopilot?.(state);
+    } catch {
+      /* the rows are written; the map catches up on the next change */
+    }
+  }
+
+  /** `{ autoEnableNew, unseen }` for Select Models and the menu dot. */
+  function getCopilotModelState() {
+    const state = loadCopilotModelState();
+    const bases = new Set(listModelVariantRows().map((row) => row.baseModelId));
+    return {
+      autoEnableNew: state ? state.autoEnableNew : false,
+      unseen: state ? state.unseen.filter((baseModelId) => bases.has(baseModelId)) : [],
+    };
+  }
+
+  function setCopilotAutoEnableNew(value) {
+    const state = loadCopilotModelState();
+    if (!state || typeof value !== 'boolean') return getCopilotModelState();
+    saveCopilotModelState({ ...state, autoEnableNew: value });
+    return getCopilotModelState();
+  }
+
+  /** Clears the "New" flags; true when one was set. */
+  function markCopilotModelsSeen() {
+    const state = loadCopilotModelState();
+    if (!state || !state.unseen.length) return false;
+    saveCopilotModelState({ ...state, unseen: [] });
+    return true;
+  }
+
   /** Stored metadata per base model (first row wins; all rows carry the same). */
   function storedMetadataByModel(rows = listModelVariantRows()) {
     const byModel = {};
@@ -772,12 +837,21 @@ export function createModelVariantCatalogService({
     const existingEnabled = new Map(existingRows.map((row) => [row.variantId, row.enabled ? 1 : 0]));
     const incomingIds = new Set(normalizedEntries.map((entry) => entry.variantId));
     const incomingBaseIds = new Set(normalizedEntries.map((entry) => entry.baseModelId));
+    const enabledBaseIds = new Set(existingRows.filter((row) => row.enabled).map((row) => row.baseModelId));
+    const modelState = loadCopilotModelState(existingRows);
+    const newBaseIds = new Set();
+    const prunedDisabledIds = new Set();
     const nowIso = new Date().toISOString();
     const tx = db.transaction(() => {
       for (const entry of normalizedEntries) {
-        const enabled = preserveEnabled && existingEnabled.has(entry.variantId)
-          ? existingEnabled.get(entry.variantId)
-          : (entry.enabled ? 1 : 0);
+        let enabled = entry.enabled ? 1 : 0;
+        if (preserveEnabled && existingEnabled.has(entry.variantId)) {
+          enabled = existingEnabled.get(entry.variantId);
+        } else if (modelState && !existingEnabled.has(entry.variantId)) {
+          const decision = decideNewCopilotVariant(modelState, entry, { siblingEnabled: enabledBaseIds.has(entry.baseModelId) });
+          enabled = decision.enabled ? 1 : 0;
+          if (decision.newModel) newBaseIds.add(entry.baseModelId);
+        }
         runVariantUpsert(entry, enabled, nowIso);
       }
       const orphanedEnabledBases = new Set();
@@ -788,6 +862,7 @@ export function createModelVariantCatalogService({
             // The runtime told us this model's exact levels; a row for a
             // level it does not offer is stale, not "unavailable".
             if (row.enabled) orphanedEnabledBases.add(row.baseModelId);
+            else prunedDisabledIds.add(row.variantId);
             modelSelectorSql.deleteVariant.run(row.variantId);
           } else {
             runVariantUpsert({ ...row, releaseStatus: 'unavailable' }, row.enabled, nowIso);
@@ -801,6 +876,8 @@ export function createModelVariantCatalogService({
         }
         // Variants that are both disabled and fully absent from the incoming
         // base set are no longer relevant; prune them so they do not linger.
+        // The model map remembers them as off for when they come back.
+        prunedDisabledIds.add(row.variantId);
         modelSelectorSql.deleteVariant.run(row.variantId);
       }
       // A selection must not silently vanish because its effort level did:
@@ -822,6 +899,21 @@ export function createModelVariantCatalogService({
       }
     });
     tx();
+    if (modelState) {
+      saveCopilotModelState({
+        ...modelState,
+        knownModels: [...new Set([...modelState.knownModels, ...incomingBaseIds])],
+        disabledVariants: [...new Set([...modelState.disabledVariants, ...prunedDisabledIds])],
+        unseen: [...new Set([...modelState.unseen, ...newBaseIds])],
+      });
+      if (newBaseIds.size) {
+        try {
+          onNewModels([...newBaseIds], modelState.autoEnableNew);
+        } catch {
+          /* the toast is best-effort */
+        }
+      }
+    }
     recomputeSortOrder();
     return getModelVariantSelectorState();
   }
@@ -839,23 +931,49 @@ export function createModelVariantCatalogService({
     return reconcileModelVariantRows(entries, { source, error, preserveEnabled, absentBasePolicy: 'reconcile', knownEffortBases });
   }
 
-  function setEnabledModelVariants(variantIds = []) {
+  /**
+   * The Select Models save. With `shownVariantIds` (the rows the browser
+   * drew) only those rows are set, on when listed in `variantIds`; every
+   * other row keeps its state, so a row a refresh added after the modal was
+   * drawn is not turned off. Without it (an older page) the list is the whole
+   * enabled set, as before.
+   */
+  function setEnabledModelVariants(variantIds = [], { shownVariantIds = null } = {}) {
     if (!modelSelectorSql?.disableAllVariants?.run || !modelSelectorSql?.enableVariant?.run) {
       return getModelVariantSelectorState();
     }
     const nextEnabled = new Set(
       Array.isArray(variantIds) ? variantIds.map((value) => String(value || '').trim()).filter(Boolean) : [],
     );
+    // Turning every row off would leave the pickers with the fallback model
+    // only; the route refuses it, and so does this.
+    if (!nextEnabled.size) return getModelVariantSelectorState();
     const existingRows = listModelVariantRows();
+    const shown = Array.isArray(shownVariantIds)
+      ? new Set(shownVariantIds.map((value) => String(value || '').trim()).filter(Boolean))
+      : null;
+    const touchedRows = shown ? existingRows.filter((row) => shown.has(row.variantId)) : existingRows;
+    const modelState = loadCopilotModelState(existingRows);
     const nowIso = new Date().toISOString();
     const tx = db.transaction(() => {
-      modelSelectorSql.disableAllVariants.run(nowIso);
-      for (const row of existingRows) {
-        if (!nextEnabled.has(row.variantId)) continue;
-        modelSelectorSql.enableVariant.run(nowIso, row.variantId);
+      if (!shown) modelSelectorSql.disableAllVariants.run(nowIso);
+      for (const row of touchedRows) {
+        if (nextEnabled.has(row.variantId)) modelSelectorSql.enableVariant.run(nowIso, row.variantId);
+        else if (shown) modelSelectorSql.disableVariant.run(nowIso, row.variantId);
       }
     });
     tx();
+    if (modelState) {
+      // A row turned on is forgotten as off; a row turned off is remembered.
+      const touchedIds = new Set(touchedRows.map((row) => row.variantId));
+      saveCopilotModelState({
+        ...modelState,
+        disabledVariants: [...new Set([
+          ...modelState.disabledVariants.filter((variantId) => !(touchedIds.has(variantId) && nextEnabled.has(variantId))),
+          ...touchedRows.filter((row) => !nextEnabled.has(row.variantId)).map((row) => row.variantId),
+        ])],
+      });
+    }
     return getModelVariantSelectorState();
   }
 
@@ -897,6 +1015,13 @@ export function createModelVariantCatalogService({
       refreshedAt: receivedMetadata ? new Date().toISOString() : modelCatalog.refreshedAt,
       error: snapshot.error ? String(snapshot.error).trim().slice(0, 300) : null,
     };
+    if (authoritative) {
+      try {
+        onAuthoritativeSnapshot({ source });
+      } catch {
+        /* the refresh clock is best-effort */
+      }
+    }
     if (modelSelectorSql?.upsertVariant?.run) {
       const existingRows = listModelVariantRows();
       const stored = storedMetadataByModel(existingRows);
@@ -1074,6 +1199,7 @@ export function createModelVariantCatalogService({
       updateSortOrderForBase: db.prepare(`UPDATE model_variants SET sort_order = ? WHERE base_model_id = ?`),
       disableAllVariants: db.prepare(`UPDATE model_variants SET enabled = 0, updated_at = ?`),
       enableVariant: db.prepare(`UPDATE model_variants SET enabled = 1, updated_at = ? WHERE variant_id = ?`),
+      disableVariant: db.prepare(`UPDATE model_variants SET enabled = 0, updated_at = ? WHERE variant_id = ?`),
       deleteVariant: db.prepare(`DELETE FROM model_variants WHERE variant_id = ?`),
       getSelectorState: db.prepare(`SELECT source, refreshed_at, error, updated_at FROM model_selector_state WHERE id = 1 LIMIT 1`),
       upsertSelectorState: db.prepare(`
@@ -1153,6 +1279,9 @@ export function createModelVariantCatalogService({
     }
     normalizeLegacyVariantIdsTx();
     recomputeSortOrder();
+    // The model map of an install from before it is built from the table as
+    // it stands now, before any snapshot adds a row.
+    loadCopilotModelState();
   }
 
   return {
@@ -1175,6 +1304,9 @@ export function createModelVariantCatalogService({
     getModelVariantSelectorState,
     upsertModelVariantCatalogEntries,
     setEnabledModelVariants,
+    getCopilotModelState,
+    setCopilotAutoEnableNew,
+    markCopilotModelsSeen,
     refreshModelVariantCatalogFromCli,
     parseModelsFromHelpConfigOutput,
     parseReasoningEffortsFromHelpOutput,

package/server/services/native-addon-build-service.mjs

@@ -0,0 +1,224 @@
+/**
+ * better-sqlite3 13 ships its binary for linux (glibc and musl), darwin and
+ * win32 on x64 and arm64, and runs no install script. Anywhere else (Android
+ * under Termux, 32-bit ARM, FreeBSD) the first database open finds no binary
+ * and throws: the binding has to be compiled from the sources the package
+ * ships. OAR runs that build itself, after an update (the Update button,
+ * `oar update`) and as `oar build-native`, never as an install script of its
+ * own package: one would bring back the install-script warning every package
+ * scanner shows for OAR, and npm 12 skips it unless the user allows it.
+ *
+ * The build is node-gyp's, the one npm bundles (npx's as the fallback), in the
+ * package's own folder with `--force_build=1`, as the package's
+ * `build-release` script runs it. It needs Python 3, make and a C++ compiler.
+ */
+import { spawn as defaultSpawn } from 'child_process';
+import fs from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+
+import { killTree, runToCompletion, tailOf } from './cli-process-runner.mjs';
+
+export const BETTER_SQLITE3_PREBUILD_PLATFORMS = Object.freeze(['linux', 'darwin', 'win32']);
+export const BETTER_SQLITE3_PREBUILD_ARCHS = Object.freeze(['x64', 'arm64']);
+export const NATIVE_BUILD_COMMAND = 'oar build-native';
+// sqlite3.c is one large file: a phone takes minutes for it.
+export const NATIVE_BUILD_TIMEOUT_MS = 30 * 60_000;
+export const TERMUX_BUILD_TOOLS = 'pkg install python clang make';
+
+const BINDING_FILE = path.join('build', 'Release', 'better_sqlite3.node');
+
+/** True where better-sqlite3 has no prebuilt binary and must be compiled. */
+export function needsSourceBuild({ platform = process.platform, arch = process.arch } = {}) {
+  return !(BETTER_SQLITE3_PREBUILD_PLATFORMS.includes(platform) && BETTER_SQLITE3_PREBUILD_ARCHS.includes(arch));
+}
+
+/** The folder of the better-sqlite3 this package loads, or null. */
+export function resolveBetterSqlite3Dir({ packageRoot, requireFrom = createRequire } = {}) {
+  try {
+    const require = requireFrom(path.join(path.resolve(String(packageRoot || '.')), 'package.json'));
+    return path.dirname(require.resolve('better-sqlite3/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** The error better-sqlite3 throws when it finds neither a prebuilt nor a built binary. */
+export function isMissingSqliteBindingError(error) {
+  const code = String(error?.code || '');
+  return (code === 'MODULE_NOT_FOUND' || code === 'ERR_DLOPEN_FAILED')
+    && /better_sqlite3\.node|better-sqlite3[\\/]prebuilds[\\/][^\\/]+\.node/.test(String(error?.message || ''));
+}
+
+/**
+ * The lines a relay prints, instead of a stack trace, when it cannot open a
+ * database because the binding is missing.
+ */
+export function missingSqliteBindingLines({ platform = process.platform, arch = process.arch, error = null } = {}) {
+  const target = `${platform}-${arch}`;
+  if (!needsSourceBuild({ platform, arch })) {
+    // There, but not loadable on this system. better-sqlite3 loads its
+    // prebuilt binding before a built one, so no build here would be used.
+    if (String(error?.code || '') === 'ERR_DLOPEN_FAILED') {
+      return [
+        `The SQLite binding that better-sqlite3 ships for ${target} does not load on this system (${String(error?.message || '').split('\n')[0]}).`,
+        'Its C library is too old for it, or the system is not one the binding supports.',
+        'Update the operating system, or run the relay on a supported one.',
+      ];
+    }
+    return [
+      `The SQLite binding of better-sqlite3 for ${target} is missing from the installed package (${String(error?.message || '').split('\n')[0]}).`,
+      'Reinstall OAR: npm install -g @oar-sh/oar',
+    ];
+  }
+  return [
+    `better-sqlite3 has no prebuilt SQLite binding for ${target}, and it has not been built here yet.`,
+    `Build it with: ${NATIVE_BUILD_COMMAND}`,
+    platform === 'android'
+      ? `It needs Python 3, make and a C++ compiler: ${TERMUX_BUILD_TOOLS}`
+      : 'It needs Python 3, make and a C++ compiler.',
+  ];
+}
+
+// The node-gyp that ships inside npm, beside this Node; null when there is none.
+function bundledNodeGyp({ execPath, platform, existsImpl, realpathImpl }) {
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
+  const nodeDir = pathImpl.dirname(String(execPath || ''));
+  const npmRoots = [];
+  if (platform !== 'win32') {
+    // <prefix>/bin/npm is a link to <prefix>/lib/node_modules/npm/bin/npm-cli.js.
+    try { npmRoots.push(pathImpl.dirname(pathImpl.dirname(realpathImpl(pathImpl.join(nodeDir, 'npm'))))); } catch {}
+    npmRoots.push(pathImpl.join(nodeDir, '..', 'lib', 'node_modules', 'npm'));
+  } else {
+    npmRoots.push(pathImpl.join(nodeDir, 'node_modules', 'npm'));
+  }
+  for (const root of npmRoots) {
+    const file = pathImpl.join(root, 'node_modules', 'node-gyp', 'bin', 'node-gyp.js');
+    if (existsImpl(file)) return file;
+  }
+  return null;
+}
+
+/**
+ * How to run node-gyp: npm's own (npm_config_node_gyp when npm set it), else
+ * `npx --yes node-gyp`. Returns { command, args, env }.
+ */
+export function resolveNodeGypInvocation({
+  execPath = process.execPath,
+  platform = process.platform,
+  env = process.env,
+  existsImpl = fs.existsSync,
+  realpathImpl = fs.realpathSync,
+} = {}) {
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
+  const nodeDir = pathImpl.dirname(String(execPath || ''));
+  const separator = platform === 'win32' ? ';' : ':';
+  const pathKey = Object.keys(env || {}).find((key) => key.toUpperCase() === 'PATH') || 'PATH';
+  // node-gyp runs `node` from the gyp files: this Node first on its PATH.
+  const childEnv = { ...env, [pathKey]: [nodeDir, String(env?.[pathKey] || '')].filter(Boolean).join(separator) };
+  // Node for Termux has no android_ndk_path in its common.gypi, which gyp
+  // then refuses as undefined; an empty one builds with Termux's own clang.
+  if (platform === 'android' && !/\bandroid_ndk_path=/.test(String(env?.GYP_DEFINES || ''))) {
+    childEnv.GYP_DEFINES = [String(env?.GYP_DEFINES || '').trim(), "android_ndk_path=''"].filter(Boolean).join(' ');
+  }
+  const fromNpm = String(env?.npm_config_node_gyp || '').trim();
+  const gyp = (fromNpm && existsImpl(fromNpm) ? fromNpm : null) || bundledNodeGyp({ execPath, platform, existsImpl, realpathImpl });
+  if (gyp) return { command: execPath, args: [gyp], env: childEnv };
+  if (platform === 'win32') {
+    // npx.cmd runs through a shell, which splits a path with a space in it
+    // (C:\Program Files): this Node with npm's npx-cli.js, else npx.cmd by name.
+    const npxCli = pathImpl.join(nodeDir, 'node_modules', 'npm', 'bin', 'npx-cli.js');
+    if (existsImpl(npxCli)) return { command: execPath, args: [npxCli, '--yes', 'node-gyp'], env: childEnv };
+    return { command: 'npx.cmd', args: ['--yes', 'node-gyp'], env: childEnv };
+  }
+  const npx = pathImpl.join(nodeDir, 'npx');
+  return { command: existsImpl(npx) ? npx : 'npx', args: ['--yes', 'node-gyp'], env: childEnv };
+}
+
+// What a failed build's output says is missing, as one line to act on.
+function missingToolHint(output, platform) {
+  const text = String(output || '');
+  const missing = /find Python|Could not find any Python|python3?: (?:not found|command not found)/i.test(text)
+    || /make: (?:not found|command not found)|not found: make|spawn make ENOENT/i.test(text)
+    || /(?:c\+\+|g\+\+|clang\+\+|cc|clang): (?:not found|command not found)|No such file or directory.*(?:c\+\+|g\+\+|clang)/i.test(text);
+  if (!missing) return null;
+  return platform === 'android'
+    ? `Install the build tools first: ${TERMUX_BUILD_TOOLS}, then run ${NATIVE_BUILD_COMMAND} again.`
+    : `Install Python 3, make and a C++ compiler (build-essential on Debian and Ubuntu), then run ${NATIVE_BUILD_COMMAND} again.`;
+}
+
+// Opens a database in a child Node with the binding just built, named by its
+// path: the default loader would take a prebuilt one first where one ships.
+function bindingLoads({ dir, execPath, spawnImpl, env }) {
+  const binding = path.join(dir, BINDING_FILE);
+  const script = `const Database = require(${JSON.stringify(dir)}); new Database(':memory:', { nativeBinding: ${JSON.stringify(binding)} }).close();`;
+  return runToCompletion(
+    () => spawnImpl(execPath, ['-e', script], { stdio: ['ignore', 'pipe', 'pipe'], env, windowsHide: true }),
+    { timeoutMs: 60_000 },
+  );
+}
+
+/**
+ * Builds the binding when this platform has no prebuilt one. `force` builds
+ * where one ships too, to check the toolchain; better-sqlite3 still loads its
+ * prebuilt binding first there. Resolves (never rejects) with { ok, status, error?, hint? }:
+ * status 'prebuilt' (nothing to do), 'built', 'failed'. Every line of the
+ * build goes to `onOutput`; what it says about itself goes to `logger.log`.
+ */
+export async function buildBetterSqlite3({
+  packageRoot,
+  force = false,
+  platform = process.platform,
+  arch = process.arch,
+  execPath = process.execPath,
+  env = process.env,
+  spawnImpl = defaultSpawn,
+  existsImpl = fs.existsSync,
+  realpathImpl = fs.realpathSync,
+  requireFrom = createRequire,
+  timeoutMs = NATIVE_BUILD_TIMEOUT_MS,
+  onOutput = null,
+  onChild = null,
+  logger = console,
+} = {}) {
+  if (!force && !needsSourceBuild({ platform, arch })) return { ok: true, status: 'prebuilt' };
+  const dir = resolveBetterSqlite3Dir({ packageRoot, requireFrom });
+  if (!dir) {
+    const error = `better-sqlite3 is not installed under ${packageRoot}`;
+    logger.error?.(`[oar] ${error}.`);
+    return { ok: false, status: 'failed', error };
+  }
+  const gyp = resolveNodeGypInvocation({ execPath, platform, env, existsImpl, realpathImpl });
+  const args = [...gyp.args, 'rebuild', '--release', '--force_build=1'];
+  logger.log?.(`[oar] Building the SQLite binding of better-sqlite3 for ${platform}-${arch} in ${dir}; this takes a few minutes.`);
+  const result = await runToCompletion(
+    () => spawnImpl(gyp.command, args, {
+      cwd: dir,
+      env: gyp.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(platform === 'win32' ? { windowsHide: true, shell: /\.cmd$/i.test(gyp.command) } : { detached: true }),
+    }),
+    {
+      timeoutMs,
+      killChild: (child, signal) => killTree(child, signal, { platform }),
+      onChild,
+      onOutput,
+    },
+  );
+  if (!result.ok || !existsImpl(path.join(dir, BINDING_FILE))) {
+    const error = result.error || `node-gyp exited with code ${result.code}`;
+    const hint = missingToolHint(result.output, platform);
+    logger.error?.(`[oar] The build of the SQLite binding failed: ${error}.`);
+    if (hint) logger.error?.(`[oar] ${hint}`);
+    else logger.error?.(`[oar] The end of its output:\n${tailOf(result.output, 2_000)}`);
+    return { ok: false, status: 'failed', error, ...(hint ? { hint } : {}) };
+  }
+  const check = await bindingLoads({ dir, execPath, spawnImpl, env: gyp.env });
+  if (!check.ok) {
+    const error = `the built binding does not load: ${tailOf(check.output || check.error || '', 500).trim()}`;
+    logger.error?.(`[oar] ${error}`);
+    return { ok: false, status: 'failed', error };
+  }
+  logger.log?.('[oar] The SQLite binding is built.');
+  return { ok: true, status: 'built' };
+}

package/server/services/oar-cli-helpers.mjs

@@ -7,6 +7,16 @@ import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import {
+  AGENT_SDK_IDS,
+  agentSdkSupport,
+  agentSdkFromCheckout,
+  findReadyAgentSdkDir,
+  getAgentSdkDescriptor,
+  readAgentSdkMarker,
+  readAgentSdkPin,
+  resolveAgentSdkRoot,
+} from './agent-sdk-paths.mjs';
 import { formatMegabytes } from './db-backup-service.mjs';
 
 export function generateAuthToken() {
@@ -86,6 +96,8 @@ const CLI_COMMANDS = {
   autostart: { words: ['signin', 'boot', 'off', 'status'], flags: ['--replace'] },
   uninstall: { flags: ['--purge'] },
   update: { flags: ['--beta'], values: ['--to'] },
+  'build-native': { flags: ['--force'] },
+  sdk: { words: ['install', 'status'], words2: [...AGENT_SDK_IDS], flags: ['--reinstall'] },
   copilot: { flags: ['--install-extension', '--no-install-extension'], values: ['--port', '--migrate-from'], forwards: true },
 };
 
@@ -116,6 +128,12 @@ export function usageText() {
     '  oar backup [--reason <text>]',
     '                         A copy of the database into the backup folder (safe while the relay runs)',
     '  oar update [--beta] [--to <version>]',
+    '  oar sdk [status]       The agent SDKs the relay installs on demand: folder, versions, state',
+    '  oar sdk install claude | cursor | koffi [--reinstall]',
+    '                         Install one now, without the relay (koffi: Windows only)',
+    '  oar build-native [--force]',
+    '                         Build the SQLite binding where no prebuilt one ships (Termux, 32-bit ARM);',
+    '                         --force builds where one ships too, which only tests the build tools',
     '  oar help               This text',
     '  oar --version',
   ].join('\n');
@@ -176,6 +194,8 @@ export function parseCliArgs(argv = []) {
       if (arg === name) index += 1;
     } else if (spec.words?.includes(arg) && words === 0) {
       words += 1;
+    } else if (spec.words2?.includes(arg) && words === 1) {
+      words += 1;
     } else if (!spec.flags?.includes(arg)) {
       return { error: arg.startsWith('-') ? `Unknown option for oar ${command}: ${arg}` : `Unexpected argument: ${arg}` };
     }
@@ -398,15 +418,14 @@ export function buildServicePath({ nodeBin, envPath = '', homeDir = '' } = {}) {
 
 /**
  * The dependencies whose install scripts OAR needs (they fetch or build a
- * native binary). npm 12 runs no install script it was not told to allow, and
- * a global install has no package.json of its own to say so; npm 10 and 11
- * accept the flag and run the scripts as before. `npm-install-scripts.test.mjs`
- * holds this list to the lockfile.
+ * native binary): none. npm 12 runs no install script it was not told to
+ * allow, so a package that gains one must be added here and passed to npm
+ * again; `npm-install-scripts.test.mjs` holds this list to the lockfile.
+ * better-sqlite3 13 has no install script (where it ships no binary, OAR
+ * builds it: native-addon-build-service.mjs), and koffi, whose script the
+ * list held, is installed on demand on Windows (agent-sdk-store.mjs).
  */
-// @oar-sh/oar itself: its preinstall copies the data an earlier version
-// kept inside the package before npm deletes it (package-data-rescue.mjs).
-export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['@oar-sh/oar', 'better-sqlite3', 'koffi']);
-export const NPM_ALLOW_SCRIPTS_ARG = `--allow-scripts=${NPM_INSTALL_SCRIPT_PACKAGES.join(',')}`;
+export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze([]);
 
 /**
  * How to run `npm install -g` so the update lands in the install that is
@@ -439,8 +458,9 @@ export function resolveNpmInvocation({
 
 /**
  * Provider CLIs `oar doctor` probes, with the args that answer fast. Cursor is
- * deliberately absent: the relay drives it through the bundled @cursor/sdk npm
- * package and never invokes a cursor-agent binary.
+ * deliberately absent: the relay drives it through the Cursor SDK it installs
+ * on demand (the agent SDK block of the report) and never invokes a
+ * cursor-agent binary.
  */
 export const DOCTOR_PROBES = Object.freeze([
   { id: 'gh (Copilot)', binary: 'gh', args: ['--version'] },
@@ -484,6 +504,50 @@ function renderBackupLines(backups, now) {
   return lines;
 }
 
+/**
+ * The agent SDKs as `oar doctor` and `oar sdk` show them, read from the disk
+ * alone (no lock, no spawn): the folder, and per SDK the pinned version, an
+ * installed one and its state. A checkout runs its devDependencies instead.
+ */
+export function describeAgentSdks({ env = process.env, platform = process.platform } = {}) {
+  // A checkout takes each SDK from its node_modules while it is installed there.
+  const fromCheckout = AGENT_SDK_IDS.every((id) => agentSdkFromCheckout(id, { env }) || getAgentSdkDescriptor(id).platforms?.includes(platform) === false);
+  const root = resolveAgentSdkRoot({ env, platform });
+  const rows = [];
+  for (const id of AGENT_SDK_IDS) {
+    const descriptor = getAgentSdkDescriptor(id);
+    let pin = null;
+    try { pin = readAgentSdkPin(id); } catch {}
+    if (!pin) {
+      rows.push({ id, label: descriptor.label, pinned: null, installed: null, state: 'pins missing from the package' });
+      continue;
+    }
+    const support = agentSdkSupport(pin);
+    if (descriptor.platforms && !descriptor.platforms.includes(platform)) continue;
+    if (agentSdkFromCheckout(id, { env })) {
+      rows.push({ id, label: descriptor.label, pinned: pin.version, installed: null, state: 'from the checkout (devDependency)' });
+      continue;
+    }
+    const ready = findReadyAgentSdkDir(id, { env, platform, root });
+    const older = ready ? null : findReadyAgentSdkDir(id, { env, platform, root, anyVersion: true });
+    const olderVersion = older ? readAgentSdkMarker(older)?.version || null : null;
+    const state = support === 'no'
+      ? 'not available on this platform'
+      : ready ? `ready${support === 'cli' ? " (runs the host's Claude Code CLI)" : ''}`
+        : olderVersion ? `${olderVersion} installed; the relay installs ${pin.version} at its next start or first chat`
+          : 'not installed (installs on first setup or first chat)';
+    rows.push({ id, label: descriptor.label, pinned: pin.version, installed: ready ? pin.version : olderVersion, state, dir: ready || older || null });
+  }
+  return { fromCheckout, root, rows };
+}
+
+export function renderAgentSdkLines(agentSdks) {
+  if (!agentSdks) return [];
+  const lines = [`  agent SDKs    : ${agentSdks.fromCheckout ? "from the checkout's node_modules (OAR_AGENT_SDK_SOURCE=store uses the store)" : agentSdks.root}`];
+  for (const row of agentSdks.rows) lines.push(`    ${row.id.padEnd(14)}: ${row.pinned ? `${row.pinned} ` : ''}${row.state}`);
+  return lines;
+}
+
 export function renderDoctorReport({
   version,
   nodeVersion,
@@ -499,6 +563,7 @@ export function renderDoctorReport({
   probes = [],
   warnings = [],
   tunnel = '',
+  agentSdks = null,
 }) {
   const yesNo = (v) => (v ? 'yes' : 'no');
   const lines = [
@@ -524,6 +589,7 @@ export function renderDoctorReport({
   for (const probe of probes) {
     lines.push(`    ${probe.id.padEnd(14)}: ${probe.ok ? probe.version || 'installed' : 'not found'}`);
   }
+  lines.push(...renderAgentSdkLines(agentSdks));
   for (const warning of warnings) lines.push(`  warning       : ${warning}`);
   return lines.join('\n');
 }

package/server/services/oar-state-migration-service.mjs

@@ -21,25 +21,15 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 
 import { DB_FILE_NAMES, LEGACY_DB_FILE_NAME, resolveDatabaseFile, sideFiles } from './database-file.mjs';
+import { resolveOarRoot } from './oar-state-root.mjs';
 import { createRelaySingletonGuard } from './relay-singleton-guard.mjs';
 
 export const MIGRATION_MARKER = '.migrated';
 const MAX_LOGS_BYTES = 50 * 1024 * 1024;
 
-export function resolveOarRoot(env = process.env, platform = process.platform) {
-  const override = String(env.OAR_STATE_ROOT || '').trim();
-  if (override) return path.resolve(override);
-  if (platform === 'win32') {
-    const appData = String(env.APPDATA || '').trim();
-    if (appData) return path.join(appData, 'oar');
-    const profile = String(env.USERPROFILE || '').trim();
-    return path.join(profile || os.homedir(), 'AppData', 'Roaming', 'oar');
-  }
-  return path.join(os.homedir(), '.oar');
-}
+export { resolveOarRoot };
 
 function defaultIsProcessAlive(pid) {
   try {

package/server/services/oar-state-root.mjs

@@ -0,0 +1,17 @@
+import os from 'node:os';
+import path from 'node:path';
+
+// The OAR state root: ~/.oar, %APPDATA%\oar on Windows, OAR_STATE_ROOT when
+// set. A module of its own, without imports of OAR's, so the relay's lock
+// check can find the agent SDK folder beside it (agent-sdk-paths.mjs).
+export function resolveOarRoot(env = process.env, platform = process.platform) {
+  const override = String(env.OAR_STATE_ROOT || '').trim();
+  if (override) return path.resolve(override);
+  if (platform === 'win32') {
+    const appData = String(env.APPDATA || '').trim();
+    if (appData) return path.join(appData, 'oar');
+    const profile = String(env.USERPROFILE || '').trim();
+    return path.join(profile || os.homedir(), 'AppData', 'Roaming', 'oar');
+  }
+  return path.join(os.homedir(), '.oar');
+}