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

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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
+found during rc.13 user QA on 2026-04-24:
+
+### RC-gated QA bug tool — target-repo hardening
+
+`totalreclaw_report_qa_bug` now refuses to file to any repo that isn't
+internal. rc.13 user QA surfaced agent-filed bug reports leaking to the
+public `p-diogo/totalreclaw` tracker despite the tool's default target
+being `p-diogo/totalreclaw-internal`.
+
+- New env var: `TOTALRECLAW_QA_REPO` lets operators point the tool at a
+  private fork. The default stays `p-diogo/totalreclaw-internal`.
+- New `resolveQaRepo(...)` guard: rejects any slug that is on the
+  public-repo denylist (includes `p-diogo/totalreclaw`,
+  `...-website`, `...-relay`, `...-plugin`, `...-hermes`) OR does not
+  end in `-internal`. The check runs before the HTTP POST is
+  constructed, so rejection never leaves the client.
+- `CONFIG.qaRepoOverride` surfaces the env var through `config.ts`
+  (keeps scanner-sensitive `process.env` reads centralized).
+- Regression test in `qa-bug-report.test.ts` mocks the public slug
+  and asserts `fetch` is NEVER called.
+
+Labels on filing unchanged — still emits `qa-bug`, `pending-triage`,
+`severity:<...>`, `component:<...>`, `rc:<...>`.
+
+### Relay pair page — PIN paste button UX
+
+The paste button on the step-1 PIN screen was silently failing under
+certain browser states. rc.14 rewrites the handler with a proper
+error taxonomy:
+
+- Capability probe up front — `navigator.clipboard.readText` missing →
+  clear "Paste unavailable on this browser" toast.
+- `NotAllowedError` → "Clipboard access denied — type the 6 digits
+  manually" (covers iOS Safari permission denial).
+- Empty clipboard → "Clipboard is empty — copy the PIN from your chat
+  first".
+- Non-digit content → "Clipboard has no digits — copy the 6-digit PIN
+  first".
+- Every failure path focuses the first PIN cell so the user can fall
+  through to manual typing without another click.
+- Errors log to `console.warn` with name + message so future failures
+  are diagnosable from browser devtools.
+
+The mockup at `docs/mockups/rc13-pair-wizard/wizard.js` gets the same
+rewrite for parity — the relay's `scripts/sync-pair-preview.mjs`
+regenerates `/pair-preview/` from this source.
+
+Fix also applies to the "Paste all 12 words" import-grid button on the
+relay production page (same taxonomy, same focus-fallback).
+
 ## [3.3.1-rc.13] — 2026-04-24
 
 Coordinated version bump with Python `2.3.1rc13`. No substantive

package/config.ts

@@ -203,6 +203,17 @@ export const CONFIG = {
     return process.env.TOTALRECLAW_QA_GITHUB_TOKEN || process.env.GITHUB_TOKEN || '';
   },
 
+  // 3.3.1-rc.14: optional target-repo override for the RC-gated QA
+  // bug-report tool. The `qa-bug-report` module enforces a
+  // "slug ends in `-internal`" rule on whatever is resolved here, so
+  // this override is only useful for forks / mirrors of the internal
+  // tracker. Leaving unset uses the production default
+  // (`p-diogo/totalreclaw-internal`). Read via getter so operators can
+  // flip the var at runtime.
+  get qaRepoOverride(): string {
+    return process.env.TOTALRECLAW_QA_REPO || '';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),

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/index.ts

@@ -5280,10 +5280,16 @@ const plugin = {
                   details: { error: 'missing_github_token' },
                 };
               }
+              // rc.14 — `repo` is resolved inside `postQaBugIssue` via
+              // `resolveQaRepo(...)`, which reads `TOTALRECLAW_QA_REPO` and
+              // refuses any slug that isn't a `-internal` fork. Pass the
+              // config-surfaced override so env reads stay in config.ts.
+              const repoOverride = CONFIG.qaRepoOverride || undefined;
               const result = await postQaBugIssue(
                 params as unknown as import('./qa-bug-report.js').QaBugArgs,
                 {
                   githubToken: token,
+                  repo: repoOverride,
                   logger: api.logger,
                 },
               );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.13",
+  "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"
   },

package/qa-bug-report.ts

@@ -18,6 +18,13 @@
  * POST. BIP-39 phrases, API keys, Telegram bot tokens, and bearer tokens
  * in headers all become `<REDACTED>` in the posted issue. Refer to
  * `redactSecrets()` for the exact rule set.
+ *
+ * Target repo safety: the default target is `p-diogo/totalreclaw-internal`.
+ * Operators can override via the `TOTALRECLAW_QA_REPO` env var, but only
+ * to another slug ending in `-internal`. Any other slug — including the
+ * public `p-diogo/totalreclaw` — is rejected with a loud error. rc.13 QA
+ * surfaced a repo-slug drift where QA findings leaked to the public
+ * tracker; rc.14 adds this fail-loud guard.
  */
 
 // ---------------------------------------------------------------------------
@@ -148,7 +155,12 @@ export interface QaBugArgs {
 export interface QaBugDeps {
   /** GitHub personal-access token with `repo` scope. */
   githubToken: string;
-  /** Repo to post to. Defaults to `p-diogo/totalreclaw-internal`. */
+  /**
+   * Repo to post to. Defaults to `resolveQaRepo(null)` → reads
+   * `TOTALRECLAW_QA_REPO` env var and falls back to
+   * `p-diogo/totalreclaw-internal`. Pass a slug (tests only) to
+   * bypass env-var lookup.
+   */
   repo?: string;
   /**
    * Abstract fetch for testing — defaults to global `fetch`. Intentionally
@@ -160,6 +172,76 @@ export interface QaBugDeps {
   logger?: { info: (msg: string) => void; warn: (msg: string) => void };
 }
 
+// ---------------------------------------------------------------------------
+// Target repo guard — fail-loud on any repo that isn't the internal tracker.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_QA_REPO = 'p-diogo/totalreclaw-internal';
+
+/**
+ * Known-public repo slugs that must never receive QA bug reports. The
+ * structural rule (`endsWith('-internal')`) below should already block
+ * these, but the explicit denylist is a belt-and-braces safety against
+ * a future rename that accidentally drops the `-internal` suffix.
+ */
+export const PUBLIC_REPOS_DENYLIST: ReadonlySet<string> = new Set([
+  'p-diogo/totalreclaw',
+  'p-diogo/totalreclaw-website',
+  'p-diogo/totalreclaw-relay',
+  'p-diogo/totalreclaw-plugin',
+  'p-diogo/totalreclaw-hermes',
+]);
+
+/**
+ * Resolve the target repo for a QA bug filing.
+ *
+ * Precedence: explicit override → `TOTALRECLAW_QA_REPO` env → default.
+ * Throws if the slug is on the public denylist or does not end in
+ * `-internal`. rc.13 QA found agent-filed bug reports leaking to the
+ * public repo; this guard makes any such drift fail loudly rather than
+ * silently leak RC ship-stopper detail.
+ *
+ * `TOTALRECLAW_QA_REPO` is the documented override var. The env-var
+ * read lives in `config.ts` (CONFIG.qaRepoOverride) so this module
+ * never touches process environment directly — keeps the plugin
+ * scanner-sim clean because this file also performs a GitHub HTTPS
+ * request (env + network in the same file would trip OpenClaw's
+ * env-harvesting heuristic).
+ *
+ * Pass the env-resolved slug (or `null`/empty for default) as
+ * `override`. Tests can inject via the second arg.
+ */
+export function resolveQaRepo(
+  override?: string | null,
+  env?: Record<string, string | undefined>,
+): string {
+  // `env` is only for test injection — production callers should
+  // pre-resolve the env value via CONFIG.qaRepoOverride and pass it as
+  // `override`. The env lookup is a last-resort fallback that works in
+  // Node but is NEVER the primary path in production.
+  const envOverride = env ? env.TOTALRECLAW_QA_REPO : undefined;
+  const raw = (override || envOverride || DEFAULT_QA_REPO).trim();
+  if (!raw || !raw.includes('/')) {
+    throw new Error(`invalid QA repo slug '${raw}': expected 'owner/name' format`);
+  }
+  if (PUBLIC_REPOS_DENYLIST.has(raw)) {
+    throw new Error(
+      `refusing to file QA bug to PUBLIC repo '${raw}'. ` +
+        'QA bug reports contain RC ship-stopper detail that must not ' +
+        "leak to public. Set TOTALRECLAW_QA_REPO to a repo ending in " +
+        "'-internal' (e.g. p-diogo/totalreclaw-internal).",
+    );
+  }
+  if (!raw.endsWith('-internal')) {
+    throw new Error(
+      `refusing to file QA bug to repo '${raw}': slug must end in ` +
+        "'-internal' (structural safety rule). Override via " +
+        'TOTALRECLAW_QA_REPO only to another internal fork.',
+    );
+  }
+  return raw;
+}
+
 const VALID_INTEGRATIONS = new Set([
   'plugin',
   'hermes',
@@ -260,7 +342,7 @@ export async function postQaBugIssue(
   if ('error' in validation) throw new Error(`invalid args: ${validation.error}`);
   if (!deps.githubToken) throw new Error('githubToken is required');
 
-  const repo = deps.repo ?? 'p-diogo/totalreclaw-internal';
+  const repo = resolveQaRepo(deps.repo ?? null);
   const url = `https://api.github.com/repos/${repo}/issues`;
 
   const title = `[qa-bug] ${redactSecrets(args.title)}`;