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

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.14] — 2026-04-24
 
 Coordinated version bump with Python `2.3.1rc14`. Two narrow bug fixes

package/embedding.ts

@@ -8,11 +8,44 @@
  * embedding model breaks search across an existing vault, so the
  * `TOTALRECLAW_EMBEDDING_MODEL` user-facing env var was removed in v1.
  *
- * Dependencies: @huggingface/transformers
+ * 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`.
  */
 
+// Type-only import — erased at compile time, no runtime dep on the package.
 // @ts-ignore - @huggingface/transformers types may not be perfect
-import { AutoTokenizer, AutoModel, pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+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}`);
+  }
+}
 
 interface ModelConfig {
   id: string;
@@ -45,14 +78,17 @@ let activeModel: ModelConfig | null = null;
 /**
  * Generate an embedding vector for the given text.
  *
- * On first call, downloads and loads the ONNX model (cached after download).
- * Subsequent calls reuse the loaded model and run in ~100ms.
+ * 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.
  */
 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.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.14",
+  "version": "3.3.1-rc.15",
   "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,16 +31,26 @@
   "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/",
@@ -54,7 +64,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 lazy-load-embedding.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },