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

package/CHANGELOG.md

@@ -4,47 +4,6 @@ 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/SKILL.md

@@ -66,7 +66,7 @@ The QR encodes ONLY the pair URL. The 6-digit PIN is a separate out-of-band conf
 
 ## Phrase safety (HARD — never break)
 
-NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup path is `totalreclaw_pair`. If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
+NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup paths are (in order of preference): (1) `totalreclaw_pair` tool; (2) if the tool is missing from your tool list — a known gap for some container-based agents, issue #87 — shell out to `openclaw totalreclaw pair generate --url-pin-only`, which emits a single-line JSON `{v,url,pin,expires_at_ms}` with zero phrase material on stdout (pair-crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
 
 ## Usage (post-setup)
 
@@ -78,7 +78,7 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 
 ## Diagnostics
 
-- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. Verify via `openclaw plugins list | grep totalreclaw`. If listed, ask the user to restart the gateway.
+- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. Verify via `openclaw plugins list | grep totalreclaw`. If listed but tools still absent (container-agent gap, issue #87), shell out to `openclaw totalreclaw pair generate --url-pin-only` on the gateway host and hand the user the `url` + `pin` from the JSON payload — do NOT suggest `openclaw totalreclaw onboard` (leaks phrase on stdout).
 - User says done but `credentials.json` missing → PIN expired or entered wrong phrase; call `totalreclaw_pair` again.
 - `onboarding required` → credentials missing; redo from the pair step.
 - `quota exceeded` → `totalreclaw_status`, then offer `totalreclaw_upgrade`.

package/embedding.ts

@@ -8,44 +8,11 @@
  * 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
  */
 
-// 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';
 
 interface ModelConfig {
   id: string;
@@ -78,17 +45,14 @@ 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.');

package/index.ts

@@ -5412,11 +5412,18 @@ const plugin = {
                 '## TotalReclaw setup pending\n\n' +
                 'TotalReclaw encrypted memory is installed but not yet set up on this machine. ' +
                 'If the user asks about memory features or wants to configure TotalReclaw, ' +
-                'call the `totalreclaw_onboarding_start` tool for instructions.\n\n' +
+                'call the `totalreclaw_pair` tool — it returns a pairing URL + 6-digit PIN ' +
+                'the user opens in a browser (phrase is generated and encrypted in-browser, ' +
+                'never leaves their device in plaintext). If `totalreclaw_pair` is not in ' +
+                'your tool list (container-based agents sometimes miss it), shell out to ' +
+                '`openclaw totalreclaw pair generate --url-pin-only` on the gateway host — ' +
+                'it emits a single JSON line `{v,url,pin,expires_at_ms}` with no phrase ' +
+                'material; hand the user the `url` and `pin`.\n\n' +
                 '**Do NOT** attempt to generate, display, or relay a recovery phrase in chat. ' +
-                'All phrase handling happens on the user\'s local terminal via ' +
-                '`openclaw totalreclaw onboard` — this keeps the phrase out of the LLM ' +
-                'provider\'s logs.',
+                '**Do NOT** run `openclaw totalreclaw onboard` — that CLI emits the recovery ' +
+                'phrase on stdout and would leak it into the LLM transcript. Use `pair` ' +
+                '(tool or `--url-pin-only` CLI) instead; `onboard` is reserved for users ' +
+                'running it directly in their own local terminal.',
             };
           }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.15",
+  "version": "3.3.1-rc.17",
   "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",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },

package/pair-cli.ts

@@ -85,8 +85,15 @@ export interface PairCliOutcome {
  *     as the session reaches a terminal state — same status-code
  *     semantics as 'human' (0 on completed, 1 on expired/rejected/error,
  *     130 on canceled).
+ *   - 'url-pin': (3.3.1-rc.15, issue #87) headless container-agent fallback.
+ *     Emits ONLY `{ v, url, pin, expires_at_ms }` — no QR ASCII, no SID,
+ *     no mode echo. Use when a container-based agent cannot see the
+ *     `totalreclaw_pair` tool (OpenClaw gateway-to-container tool-injection
+ *     gap) and must shell out to the CLI. Guarantees zero phrase material
+ *     on stdout by construction — pair-crypto is x25519-only and the slim
+ *     payload carries nothing BIP-39-adjacent.
  */
-export type PairCliOutputMode = 'human' | 'json';
+export type PairCliOutputMode = 'human' | 'json' | 'url-pin';
 
 /**
  * JSON payload emitted by runPairCli when outputMode === 'json'. Printed
@@ -103,6 +110,17 @@ export interface PairCliJsonPayload {
   qr_ascii: string;
 }
 
+/**
+ * Slim payload for outputMode === 'url-pin'. Intentionally a subset of
+ * `PairCliJsonPayload` with no QR ASCII, SID, or mode echo. Issue #87.
+ */
+export interface PairCliUrlPinPayload {
+  v: 1;
+  url: string;
+  pin: string;
+  expires_at_ms: number;
+}
+
 // ---------------------------------------------------------------------------
 // Default stdout IO
 // ---------------------------------------------------------------------------
@@ -213,9 +231,11 @@ export async function runPairCli(
     return { status: 'error', error: msg };
   }
 
-  // 2. Render the QR — promise-based so both human + json modes share it.
+  // 2. Build the URL unconditionally, but only render the QR for modes
+  //    that actually emit it. url-pin mode skips the renderer entirely —
+  //    no CPU cost, no qrcode-terminal import, no ASCII on stdout.
   const url = deps.renderPairingUrl(session);
-  const qrAscii = await new Promise<string>((resolve) => {
+  const qrAscii = outputMode === 'url-pin' ? '' : await new Promise<string>((resolve) => {
     // Guard against QR renderers that never fire their callback (shouldn't
     // happen with qrcode-terminal, but defensive): a 10-second timeout
     // returns an empty string so we never hang the pairing flow.
@@ -241,8 +261,16 @@ export async function runPairCli(
     }
   });
 
-  // 3. Emit the visible surface (JSON first — single line — or human copy).
-  if (outputMode === 'json') {
+  // 3. Emit the visible surface (JSON/url-pin first — single line — or human copy).
+  if (outputMode === 'url-pin') {
+    const payload: PairCliUrlPinPayload = {
+      v: 1,
+      url,
+      pin: session.secondaryCode,
+      expires_at_ms: session.expiresAtMs,
+    };
+    stdout.write(JSON.stringify(payload) + '\n');
+  } else if (outputMode === 'json') {
     const payload: PairCliJsonPayload = {
       v: 1,
       sid: session.sid,
@@ -276,7 +304,9 @@ export async function runPairCli(
     canceled = true;
   });
 
-  // 5. Poll
+  // 5. Poll — status transitions only surface in human mode; json/url-pin
+  //    modes stay silent after the single payload line so agents parsing
+  //    stdout get one JSON line and an exit code, nothing else.
   const emitStatus = (text: string): void => {
     if (outputMode === 'human') stdout.write(text);
   };
@@ -399,14 +429,19 @@ export function registerPairCli(
       'Pair a remote browser device to this gateway (mode = generate | import; default generate)',
     )
     .option('--json', 'Emit a single JSON payload (url/pin/sid/qr_ascii) instead of the human-readable banner. Enables agent-driven pairing.')
+    .option('--url-pin-only', 'Emit ONLY {v,url,pin,expires_at_ms} — no QR ASCII, no SID, no mode echo. Headless fallback for container-based agents where the totalreclaw_pair tool is not injected (issue #87). Zero phrase exposure on stdout.')
     .option('--timeout <sec>', 'Session TTL in seconds (default: 900 = 15 min, matches pair-session-store default)')
     .action(async (...args: unknown[]) => {
       // commander passes: [modeArg, options, cmd]
       const modeRaw = typeof args[0] === 'string' ? args[0] : undefined;
-      const opts = (args[1] ?? {}) as { json?: boolean; timeout?: string | number };
+      const opts = (args[1] ?? {}) as { json?: boolean; urlPinOnly?: boolean; timeout?: string | number };
       const mode: PairCliMode =
         modeRaw === 'import' || modeRaw === 'imp' ? 'import' : 'generate';
-      const outputMode: PairCliOutputMode = opts.json ? 'json' : 'human';
+      // --url-pin-only wins over --json when both are passed, since it is
+      // strictly the tighter surface (no QR, no SID). The flag is a subset.
+      const outputMode: PairCliOutputMode = opts.urlPinOnly
+        ? 'url-pin'
+        : opts.json ? 'json' : 'human';
       let ttlSeconds: number | undefined;
       if (typeof opts.timeout === 'number' && Number.isFinite(opts.timeout)) {
         ttlSeconds = opts.timeout;