@totalreclaw/totalreclaw 3.3.1-rc.17 → 3.3.1-rc.18

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.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
 
 Coordinated version bump with Python `2.3.1rc14`. Two narrow bug fixes

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

@@ -9,10 +9,17 @@
  * `TOTALRECLAW_EMBEDDING_MODEL` user-facing env var was removed in v1.
  *
  * 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.
  */
 
 // @ts-ignore - @huggingface/transformers types may not be perfect
 import { AutoTokenizer, AutoModel, pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { downloadWithUX, getDownloadTimeoutMs } from './download-ux.js';
 
 interface ModelConfig {
   id: string;
@@ -54,20 +61,36 @@ export async function generateEmbedding(
 ): Promise<number[]> {
   if (!activeModel) {
     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.17",
+  "version": "3.3.1-rc.18",
   "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": [
@@ -54,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",
+    "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"
   },