@totalreclaw/totalreclaw 3.3.1-rc.15 → 3.3.1-rc.16

package/CHANGELOG.md

@@ -4,46 +4,37 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.3.1-rc.15] — 2026-04-24
-
-Install-time unblock for bandwidth-constrained hosts. Lazy-loads the ONNX
-runtime instead of forcing a ~216MB download during `openclaw plugins
-install`.
-
-### Lazy-loaded ONNX / `@huggingface/transformers`
-
-`openclaw plugins install @totalreclaw/totalreclaw` on slow hosts (VPNs,
-CI containers with limited bandwidth, metered connections) was exceeding
-the plugin-install timeout mid-download and getting SIGTERM'd, leaving
-the plugin partially installed. Root cause: `@huggingface/transformers`
-was a direct `dependency`, which transitively pulled
-`onnxruntime-node`'s postinstall binary fetch (~216MB from GitHub
-Releases).
-
-- `@huggingface/transformers` and `onnxruntime-node` moved from
-  `dependencies` to optional `peerDependencies`
-  (`peerDependenciesMeta.<name>.optional: true`). npm v7+ and the
-  OpenClaw install path (`--legacy-peer-deps`) both skip these by
-  default — plugin install is now lean.
-- `embedding.ts` converts the static
-  `import { AutoTokenizer, AutoModel, pipeline } from
-  '@huggingface/transformers'` into a dynamic `await import(...)` on
-  the first `generateEmbedding` call. If the optional peer is missing,
-  the error surfaces a clear install hint:
-  `npm install @huggingface/transformers`.
-- New regression test `lazy-load-embedding.test.ts` asserts the
-  invariants (no top-level static runtime import; heavy packages not in
-  `dependencies`; peer-dep `optional` flag set) so a future refactor
-  can't silently reintroduce the install-time block.
-
-**User impact:** users on constrained hosts can now install the plugin
-without the 216MB download. Users who want semantic memory (recall /
-search over encrypted facts) install `@huggingface/transformers`
-separately — one-time, resumable if it times out.
-
-Fixes [issue #92][i92] (QA bug 6 of 10, split from #84).
-
-[i92]: https://github.com/p-diogo/totalreclaw-internal/issues/92
+## [3.3.1-rc.16] — 2026-04-24
+
+Fixes #92 — slow-host install times out during ONNX-runtime / embedding-model
+download. ONNX stays mandatory (no opt-in flag); first-call download is now
+wrapped with timeout, progress, and retry UX so slow connections succeed
+instead of silently hanging until OpenClaw SIGTERMs.
+
+### Embedding-model download UX
+
+- New `download-ux.ts` module — pure stdlib, no third-party imports — exposes
+  `downloadWithUX(label, fn, opts)`. Wraps a download promise with:
+  - **Per-attempt timeout**, default 600s (covers ~290 KB/s for the 344 MB
+    Harrier model). Configurable via env `TOTALRECLAW_ONNX_INSTALL_TIMEOUT`
+    (in seconds). Per-attempt timeout grows 1x/2x/4x across retries.
+  - **60s keep-alive log** during long downloads so users on slow networks
+    see "still downloading… (Ns elapsed)" rather than a frozen prompt.
+  - **3-attempt exponential-backoff retry** (5s/10s backoff between attempts)
+    to absorb transient network blips.
+  - **Loud actionable error** on exhaustion: names the env var to extend the
+    timeout and the exact `openclaw plugins install totalreclaw` command to
+    rerun.
+- `embedding.ts` now wraps `AutoTokenizer.from_pretrained`,
+  `AutoModel.from_pretrained`, and the `pipeline()` call with
+  `downloadWithUX`. Prints a user-visible "Downloading embedding model
+  (~344MB) — this may take a few minutes on slower connections. Please wait."
+  message before the first download starts.
+- ONNX remains a mandatory hard `dependency` (no `[embedding]`-style opt-in
+  extra). Recall accuracy is unchanged.
+- Regression: `test_issue_92_onnx_download_ux.test.ts` exercises happy path,
+  transient failure → retry, full exhaustion, per-attempt timeout, and
+  keep-alive cadence. Wired into the plugin `npm test` chain.
 
 ## [3.3.1-rc.14] — 2026-04-24
 

package/download-ux.ts

@@ -0,0 +1,91 @@
+/**
+ * download-ux.ts — Wrapper for heavy first-call downloads (rc.16, fixes #92).
+ *
+ * Wraps a download promise with:
+ *   - per-attempt timeout (default 600s, override via TOTALRECLAW_ONNX_INSTALL_TIMEOUT in seconds)
+ *   - 60s keep-alive log so slow-bandwidth users don't think it's frozen
+ *   - 3-attempt exponential-backoff retry (per-attempt timeout grows 1x/2x/4x)
+ *   - loud actionable error after exhaustion
+ *
+ * No third-party imports here — pure stdlib so the unit test can exercise it
+ * without pulling the heavy `@huggingface/transformers` chain.
+ */
+
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 600_000;
+const KEEPALIVE_INTERVAL_MS = 60_000;
+const MAX_DOWNLOAD_ATTEMPTS = 3;
+
+export function getDownloadTimeoutMs(): number {
+  const raw = process.env.TOTALRECLAW_ONNX_INSTALL_TIMEOUT;
+  if (!raw) return DEFAULT_DOWNLOAD_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_DOWNLOAD_TIMEOUT_MS;
+  // Spec accepts seconds; convert to ms.
+  return Math.floor(parsed * 1000);
+}
+
+export interface DownloadWithUXOpts {
+  /** Override the per-attempt base timeout in ms (env var takes precedence by default). */
+  timeoutMs?: number;
+  /** Override the keep-alive cadence in ms. */
+  keepaliveMs?: number;
+  /** Override the max attempts. */
+  maxAttempts?: number;
+  /** Logger override (defaults to console.error). */
+  log?: (msg: string) => void;
+  /** Sleep override for tests; defaults to setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export async function downloadWithUX<T>(
+  label: string,
+  download: () => Promise<T>,
+  opts?: DownloadWithUXOpts,
+): Promise<T> {
+  const baseTimeoutMs = opts?.timeoutMs ?? getDownloadTimeoutMs();
+  const keepaliveMs = opts?.keepaliveMs ?? KEEPALIVE_INTERVAL_MS;
+  const maxAttempts = opts?.maxAttempts ?? MAX_DOWNLOAD_ATTEMPTS;
+  const log = opts?.log ?? ((msg: string) => console.error(msg));
+  const sleep = opts?.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
+
+  let lastErr: unknown = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const attemptTimeoutMs = baseTimeoutMs * Math.pow(2, attempt - 1);
+    const startedAt = Date.now();
+    const keepaliveTimer = setInterval(() => {
+      const elapsedSec = Math.floor((Date.now() - startedAt) / 1000);
+      log(`[TotalReclaw] ${label}: still downloading… (${elapsedSec}s elapsed, attempt ${attempt}/${maxAttempts})`);
+    }, keepaliveMs);
+
+    try {
+      const result = await Promise.race([
+        download(),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error(`Download timeout after ${Math.floor(attemptTimeoutMs / 1000)}s (attempt ${attempt}/${maxAttempts})`)),
+            attemptTimeoutMs,
+          ),
+        ),
+      ]);
+      clearInterval(keepaliveTimer);
+      return result;
+    } catch (err) {
+      clearInterval(keepaliveTimer);
+      lastErr = err;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (attempt < maxAttempts) {
+        const backoffMs = Math.min(5_000 * Math.pow(2, attempt - 1), 30_000);
+        log(`[TotalReclaw] ${label}: attempt ${attempt} failed (${msg}). Retrying in ${Math.floor(backoffMs / 1000)}s…`);
+        await sleep(backoffMs);
+      }
+    }
+  }
+
+  const finalMsg = lastErr instanceof Error ? lastErr.message : String(lastErr);
+  throw new Error(
+    `[TotalReclaw] Embedding model download failed after ${maxAttempts} attempts (last error: ${finalMsg}). ` +
+      `Check your network connection and retry: \`openclaw plugins install totalreclaw\`. ` +
+      `On slow connections, set TOTALRECLAW_ONNX_INSTALL_TIMEOUT=1200 (in seconds) to extend the per-attempt timeout.`,
+  );
+}

package/embedding.ts

@@ -8,44 +8,18 @@
  * embedding model breaks search across an existing vault, so the
  * `TOTALRECLAW_EMBEDDING_MODEL` user-facing env var was removed in v1.
  *
- * Dependencies: @huggingface/transformers is declared as an optional peer
- * dependency. It is lazy-loaded on the first `generateEmbedding` call so
- * `openclaw plugins install @totalreclaw/totalreclaw` does not block on the
- * ~216MB onnxruntime-node native-binary download. Install it separately to
- * enable semantic search: `npm install @huggingface/transformers`.
+ * Dependencies: @huggingface/transformers
+ *
+ * Download UX (rc.16, fixes #92):
+ *   First-call download is wrapped via `downloadWithUX` from `download-ux.ts`
+ *   — configurable timeout (`TOTALRECLAW_ONNX_INSTALL_TIMEOUT`, default 600s),
+ *   60s keep-alive, 3-attempt exponential-backoff retry, loud actionable
+ *   failure. Slow-bandwidth hosts no longer see a silent freeze.
  */
 
-// Type-only import — erased at compile time, no runtime dep on the package.
 // @ts-ignore - @huggingface/transformers types may not be perfect
-import type { FeatureExtractionPipeline } from '@huggingface/transformers';
-
-type HFTransformers = typeof import('@huggingface/transformers');
-
-/** Cached module handle after first successful dynamic import. */
-let transformersModule: HFTransformers | null = null;
-
-/**
- * Lazily import @huggingface/transformers. The package is declared as an
- * optional peer dependency so the plugin installs on bandwidth-constrained
- * hosts without pulling the onnxruntime-node native binary (~216MB). On first
- * use, try to load it; if the user never installed it, surface a clear
- * actionable error with the install command.
- */
-async function loadTransformers(): Promise<HFTransformers> {
-  if (transformersModule) return transformersModule;
-  try {
-    // @ts-ignore - dynamic import target is the optional peer dep
-    transformersModule = (await import('@huggingface/transformers')) as HFTransformers;
-    return transformersModule;
-  } catch (err) {
-    const hint =
-      '[TotalReclaw] @huggingface/transformers is not installed. ' +
-      'Semantic memory requires it (one-time ~216MB download of ONNX runtime + model). ' +
-      'Install with: npm install @huggingface/transformers';
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new Error(`${hint}\nUnderlying load error: ${detail}`);
-  }
-}
+import { AutoTokenizer, AutoModel, pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { downloadWithUX, getDownloadTimeoutMs } from './download-ux.js';
 
 interface ModelConfig {
   id: string;
@@ -78,32 +52,45 @@ let activeModel: ModelConfig | null = null;
 /**
  * Generate an embedding vector for the given text.
  *
- * On first call, dynamically imports @huggingface/transformers (requires it
- * to be installed — see module docstring) and downloads the ONNX model
- * (cached after download). Subsequent calls reuse the loaded module + model
- * and run in ~100ms.
+ * On first call, downloads and loads the ONNX model (cached after download).
+ * Subsequent calls reuse the loaded model and run in ~100ms.
  */
 export async function generateEmbedding(
   text: string,
   options?: { isQuery?: boolean },
 ): Promise<number[]> {
   if (!activeModel) {
-    const { AutoTokenizer, AutoModel, pipeline } = await loadTransformers();
     activeModel = getModelConfig();
-    console.error(`[TotalReclaw] Downloading embedding model (${activeModel.size}, one-time setup)...`);
-    console.error('[TotalReclaw] This enables semantic search across your encrypted memories.');
+    const timeoutSec = Math.floor(getDownloadTimeoutMs() / 1000);
+    console.error(
+      `[TotalReclaw] Downloading embedding model (${activeModel.size}) — this may take a few minutes on slower connections. Please wait.`,
+    );
+    console.error(
+      `[TotalReclaw] One-time setup. Per-attempt timeout: ${timeoutSec}s (configurable via TOTALRECLAW_ONNX_INSTALL_TIMEOUT). Cached after first download.`,
+    );
 
     if (activeModel.pooling === 'sentence_embedding') {
       // Harrier: use AutoModel (pipeline doesn't support sentence_embedding output)
-      autoTokenizer = await AutoTokenizer.from_pretrained(activeModel.id);
-      autoModel = await AutoModel.from_pretrained(activeModel.id, {
-        dtype: activeModel.dtype as any,
-      });
+      autoTokenizer = await downloadWithUX(
+        'tokenizer',
+        () => AutoTokenizer.from_pretrained(activeModel!.id),
+      );
+      autoModel = await downloadWithUX(
+        'embedding model',
+        () =>
+          AutoModel.from_pretrained(activeModel!.id, {
+            dtype: activeModel!.dtype as any,
+          }),
+      );
     } else {
       // e5-small / Qwen: use pipeline
-      pipelineExtractor = await pipeline('feature-extraction', activeModel.id, {
-        dtype: activeModel.dtype as any,
-      });
+      pipelineExtractor = await downloadWithUX(
+        'embedding pipeline',
+        () =>
+          pipeline('feature-extraction', activeModel!.id, {
+            dtype: activeModel!.dtype as any,
+          }),
+      );
     }
     console.error('[TotalReclaw] Embedding model ready. Future startups will be instant.');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.15",
+  "version": "3.3.1-rc.16",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -31,26 +31,16 @@
   "author": "TotalReclaw Team",
   "license": "MIT",
   "dependencies": {
+    "@huggingface/transformers": "^4.0.1",
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
     "@types/qrcode": "^1.5.6",
     "@types/ws": "^8.5.12",
+    "onnxruntime-node": "^1.24.0",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.3"
   },
-  "peerDependencies": {
-    "@huggingface/transformers": "^4.0.1",
-    "onnxruntime-node": "^1.24.0"
-  },
-  "peerDependenciesMeta": {
-    "@huggingface/transformers": {
-      "optional": true
-    },
-    "onnxruntime-node": {
-      "optional": true
-    }
-  },
   "files": [
     "*.ts",
     "import-adapters/",
@@ -64,7 +54,7 @@
     "skill.json"
   ],
   "scripts": {
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx lazy-load-embedding.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },