@totalreclaw/totalreclaw 3.3.1-rc.8 → 3.3.1

package/dist/crypto.js

@@ -0,0 +1,138 @@
+/**
+ * TotalReclaw Plugin - Crypto Operations (WASM-backed)
+ *
+ * Thin re-exports over `@totalreclaw/core` WASM module. Same function
+ * signatures as the previous implementation so callers don't need to change.
+ *
+ * The WASM module handles BIP-39 key derivation, XChaCha20-Poly1305 encrypt/
+ * decrypt, SHA-256 blind indices, HMAC-SHA256 content fingerprints,
+ * and LSH seed derivation.
+ *
+ * Key derivation chain (BIP-39 — handled by WASM):
+ *   mnemonic -> BIP-39 PBKDF2 -> 512-bit seed
+ *     -> HKDF-SHA256(seed, salt, "totalreclaw-auth-key-v1",       32) -> authKey
+ *     -> HKDF-SHA256(seed, salt, "totalreclaw-encryption-key-v1", 32) -> encryptionKey
+ *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
+ */
+// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
+// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
+// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
+// this file called bare `require('@totalreclaw/core')` and every consumer
+// died with `require is not defined`. Matches the pattern already used by
+// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
+// retype-setscope. See issue #124.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
+let _wasm = null;
+function getWasm() {
+    if (!_wasm)
+        _wasm = requireWasm('@totalreclaw/core');
+    return _wasm;
+}
+// ---------------------------------------------------------------------------
+// BIP-39 Validation
+// ---------------------------------------------------------------------------
+/**
+ * Check if the input looks like a BIP-39 mnemonic (12 or 24 words).
+ *
+ * Lenient: accepts phrases where all words look like valid BIP-39 words
+ * (allows invalid checksums, which LLMs sometimes generate).
+ */
+export function isBip39Mnemonic(input) {
+    const words = input.trim().split(/\s+/);
+    return words.length === 12 || words.length === 24;
+}
+// Re-export for backward compatibility
+export const validateMnemonic = isBip39Mnemonic;
+// ---------------------------------------------------------------------------
+// Key Derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derive auth, encryption, and dedup keys from a recovery phrase.
+ *
+ * Delegates to the WASM module for BIP-39 seed derivation and HKDF
+ * key separation. Uses the lenient variant for phrases where all words
+ * are valid but the checksum fails.
+ *
+ * @param password     - BIP-39 12/24-word mnemonic
+ * @param existingSalt - Ignored for BIP-39 path (salt is deterministic)
+ */
+export function deriveKeys(password, existingSalt) {
+    const trimmed = password.trim();
+    // Try strict validation first, fall back to lenient
+    let result;
+    try {
+        result = getWasm().deriveKeysFromMnemonic(trimmed);
+    }
+    catch {
+        result = getWasm().deriveKeysFromMnemonicLenient(trimmed);
+    }
+    return {
+        authKey: Buffer.from(result.auth_key, 'hex'),
+        encryptionKey: Buffer.from(result.encryption_key, 'hex'),
+        dedupKey: Buffer.from(result.dedup_key, 'hex'),
+        salt: Buffer.from(result.salt, 'hex'),
+    };
+}
+// ---------------------------------------------------------------------------
+// LSH Seed Derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derive a 32-byte seed for the LSH hasher.
+ *
+ * Delegates to the WASM module.
+ */
+export function deriveLshSeed(password, salt) {
+    const seedHex = getWasm().deriveLshSeed(password.trim(), salt.toString('hex'));
+    return new Uint8Array(Buffer.from(seedHex, 'hex'));
+}
+// ---------------------------------------------------------------------------
+// Auth Key Hash
+// ---------------------------------------------------------------------------
+/**
+ * Compute the SHA-256 hash of the auth key.
+ */
+export function computeAuthKeyHash(authKey) {
+    return getWasm().computeAuthKeyHash(authKey.toString('hex'));
+}
+// ---------------------------------------------------------------------------
+// XChaCha20-Poly1305 Encrypt / Decrypt
+// ---------------------------------------------------------------------------
+/**
+ * Encrypt a UTF-8 plaintext string with XChaCha20-Poly1305.
+ *
+ * Wire format (base64-encoded):
+ *   [nonce: 24 bytes][tag: 16 bytes][ciphertext: variable]
+ */
+export function encrypt(plaintext, encryptionKey) {
+    return getWasm().encrypt(plaintext, encryptionKey.toString('hex'));
+}
+/**
+ * Decrypt a base64-encoded XChaCha20-Poly1305 blob back to a UTF-8 string.
+ */
+export function decrypt(encryptedBase64, encryptionKey) {
+    return getWasm().decrypt(encryptedBase64, encryptionKey.toString('hex'));
+}
+// ---------------------------------------------------------------------------
+// Blind Indices
+// ---------------------------------------------------------------------------
+/**
+ * Generate blind indices (SHA-256 hashes of tokens) for a text string.
+ *
+ * Delegates to the WASM module which performs tokenization, stemming,
+ * and SHA-256 hashing.
+ */
+export function generateBlindIndices(text) {
+    return getWasm().generateBlindIndices(text);
+}
+// ---------------------------------------------------------------------------
+// Content Fingerprint (Dedup)
+// ---------------------------------------------------------------------------
+/**
+ * Compute an HMAC-SHA256 content fingerprint for exact-duplicate detection.
+ *
+ * @returns 64-character hex string.
+ */
+export function generateContentFingerprint(plaintext, dedupKey) {
+    return getWasm().generateContentFingerprint(plaintext, dedupKey.toString('hex'));
+}

package/dist/digest-sync.js

@@ -0,0 +1,361 @@
+/**
+ * TotalReclaw Plugin — digest read path (Stage 3b).
+ *
+ * Loads the latest digest claim from the subgraph, checks staleness, and
+ * returns the pre-compiled `promptText` for injection into before_agent_start.
+ * Triggers background recompilation (non-blocking) when the digest is stale
+ * and the guard conditions (>=10 new claims OR >=24h) are met.
+ *
+ * The digest is stored on-chain as a regular encrypted fact where the
+ * decrypted content is a canonical Claim with category="dig" and a
+ * distinctive blind-index marker `DIGEST_TRAPDOOR`.
+ */
+import { createRequire } from 'node:module';
+import { DIGEST_CLAIM_CAP, DIGEST_TRAPDOOR, buildDigestClaim, extractDigestFromClaim, hoursSince, isDigestStale, shouldRecompile, } from './claims-helper.js';
+const requireWasm = createRequire(import.meta.url);
+let _wasm = null;
+function getWasm() {
+    if (!_wasm)
+        _wasm = requireWasm('@totalreclaw/core');
+    return _wasm;
+}
+// ---------------------------------------------------------------------------
+// Stub / tombstone blob detection
+// ---------------------------------------------------------------------------
+/**
+ * Is this subgraph-stored blob a supersede tombstone or other non-content
+ * stub? The 3.0.7-rc.1 QA found that 7 of 25 facts on the QA wallet had
+ * `encryptedBlob == "0x00"` — a 1-byte stub written as a supersede
+ * tombstone. The digest pipeline attempted to decrypt these unconditionally
+ * and produced 5 `Digest: decrypt failed … Encrypted data too short`
+ * warnings per QA window.
+ *
+ * We deliberately ONLY short-circuit shapes that cannot plausibly contain
+ * a real XChaCha20-Poly1305 payload — a valid ciphertext must be at
+ * least 40 bytes (24B nonce + 16B tag). We stay conservative about
+ * "short-but-non-stub" blobs: if someone's wire format changes and we
+ * see a 30-byte blob, that's a legitimate decrypt-failure case worth
+ * logging as a WARN, not silently skipping. So the check is:
+ *
+ *   - Empty string                        → stub
+ *   - Just the `0x` / `0X` prefix         → stub
+ *   - All-zero hex (e.g. "0x00", "00")    → stub (explicit tombstone)
+ *
+ * Anything else falls through to the decrypt attempt.
+ *
+ * Called from both `loadLatestDigest` (digest read path) and
+ * `fetchAllActiveClaims` (digest recompile path).
+ */
+export function isStubBlob(hex) {
+    if (typeof hex !== 'string')
+        return true;
+    const stripped = (hex.startsWith('0x') || hex.startsWith('0X')) ? hex.slice(2) : hex;
+    if (stripped.length === 0)
+        return true;
+    // All-zero hex is the explicit tombstone shape the relay emits
+    // when marking a fact superseded (seen as "0x00" on the QA wallet,
+    // but any "00...00" of any length is semantically the same).
+    return /^0+$/i.test(stripped);
+}
+// ---------------------------------------------------------------------------
+// Recompile-in-progress guard (in-memory, per-process)
+// ---------------------------------------------------------------------------
+let _recompileInProgress = false;
+/** Is a digest recompilation currently running for this process? */
+export function isRecompileInProgress() {
+    return _recompileInProgress;
+}
+/** Attempt to acquire the recompile lock. Returns true on success. */
+export function tryBeginRecompile() {
+    if (_recompileInProgress)
+        return false;
+    _recompileInProgress = true;
+    return true;
+}
+/** Release the recompile lock — always call in a finally block. */
+export function endRecompile() {
+    _recompileInProgress = false;
+}
+/** Test-only helper to reset module state between cases. */
+export function __resetDigestSyncState() {
+    _recompileInProgress = false;
+}
+// ---------------------------------------------------------------------------
+// Pure staleness + guard evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Combine staleness + guard checks into one decision.
+ *
+ * The caller still needs to consult `isRecompileInProgress()` before firing
+ * the background task — this function is purely about the digest's age.
+ */
+export function evaluateDigestState(input) {
+    const stale = isDigestStale(input.digestVersion, input.currentMaxCreatedAt);
+    if (!stale)
+        return { stale: false, recompile: false };
+    const recompile = shouldRecompile({
+        countNewClaims: input.countNewClaims,
+        hoursSinceCompilation: input.hoursSinceCompilation,
+    });
+    return { stale: true, recompile };
+}
+// ---------------------------------------------------------------------------
+// Core compilation (pure, no I/O)
+// ---------------------------------------------------------------------------
+/**
+ * Compile a Digest JSON from an array of Claim JSON.
+ *
+ * - `mode === 'template'` or `llmFn === null` → template path.
+ * - `mode === 'on'` with a non-null `llmFn` → LLM path with template fallback.
+ *   Any parsing/assembly/LLM failure logs a warning and falls back silently.
+ * - Claim count above DIGEST_CLAIM_CAP forces the template path regardless
+ *   of mode, to keep LLM token cost bounded.
+ *
+ * Returns the Digest JSON as produced by the WASM core.
+ */
+export async function compileDigestCore(input) {
+    const { claimsJson, nowUnixSeconds, mode, llmFn, logger } = input;
+    const core = getWasm();
+    const nowBig = BigInt(Math.floor(nowUnixSeconds));
+    // Check whether we should even attempt the LLM path.
+    let useLlm = mode === 'on' && llmFn !== null;
+    if (useLlm) {
+        try {
+            const parsedClaims = JSON.parse(claimsJson);
+            if (!Array.isArray(parsedClaims) || parsedClaims.length === 0) {
+                useLlm = false;
+            }
+            else if (parsedClaims.length > DIGEST_CLAIM_CAP) {
+                logger.info(`Digest: ${parsedClaims.length} active claims > cap ${DIGEST_CLAIM_CAP}; using template path`);
+                useLlm = false;
+            }
+        }
+        catch {
+            useLlm = false;
+        }
+    }
+    if (useLlm && llmFn) {
+        try {
+            const prompt = core.buildDigestPrompt(claimsJson);
+            const raw = await llmFn(prompt);
+            if (!raw || typeof raw !== 'string' || raw.trim().length === 0) {
+                throw new Error('LLM returned empty response');
+            }
+            const parsedResponse = core.parseDigestResponse(raw);
+            return core.assembleDigestFromLlm(parsedResponse, claimsJson, nowBig);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`Digest LLM compilation failed, falling back to template: ${msg}`);
+            // fall through to template path
+        }
+    }
+    return core.buildTemplateDigest(claimsJson, nowBig);
+}
+export async function loadLatestDigest(owner, authKeyHex, encryptionKey, deps, logger) {
+    let results;
+    try {
+        results = await deps.searchSubgraph(owner, [DIGEST_TRAPDOOR], 10, authKeyHex);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`Digest: subgraph query failed: ${msg}`);
+        return null;
+    }
+    if (!results || results.length === 0)
+        return null;
+    // Pick the highest createdAt (client-generated Unix seconds) among rows
+    // with a real (non-stub) blob. Stub blobs are supersede tombstones —
+    // see `isStubBlob` above; attempting to decrypt one produces a noisy
+    // `Digest: decrypt failed … Encrypted data too short` WARN. We filter
+    // them out pre-ranking so we prefer a slightly-older real digest over
+    // a newer tombstone. If EVERY candidate is a stub, return null quietly.
+    let best = null;
+    let stubCount = 0;
+    for (const r of results) {
+        if (isStubBlob(r.encryptedBlob)) {
+            stubCount++;
+            continue;
+        }
+        const createdAt = parseInt(r.createdAt ?? r.timestamp ?? '0', 10) || 0;
+        if (!best || createdAt > best.createdAt) {
+            best = { id: r.id, encryptedBlob: r.encryptedBlob, createdAt };
+        }
+    }
+    if (!best) {
+        if (stubCount > 0) {
+            logger.info(`Digest: all ${stubCount} candidates were tombstone stubs — no digest available`);
+        }
+        return null;
+    }
+    try {
+        const decrypted = deps.decryptFromHex(best.encryptedBlob, encryptionKey);
+        const canonical = getWasm().parseClaimOrLegacy(decrypted);
+        const digest = extractDigestFromClaim(canonical);
+        if (!digest) {
+            logger.warn(`Digest: blob ${best.id.slice(0, 10)}… did not parse as a digest claim`);
+            return null;
+        }
+        return { digest, claimId: best.id, createdAt: best.createdAt };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`Digest: decrypt failed for ${best.id.slice(0, 10)}…: ${msg}`);
+        return null;
+    }
+}
+/** How many recent facts we fetch to drive the recompile guard. */
+export const DIGEST_RECENCY_PROBE_LIMIT = 10;
+export async function getDigestRecencyProbe(owner, authKeyHex, deps) {
+    let results = [];
+    try {
+        results = await deps.searchSubgraphBroadened(owner, DIGEST_RECENCY_PROBE_LIMIT, authKeyHex);
+    }
+    catch {
+        return { maxCreatedAt: 0, countNewerThan: () => 0 };
+    }
+    if (!results || results.length === 0) {
+        return { maxCreatedAt: 0, countNewerThan: () => 0 };
+    }
+    const createdAts = [];
+    for (const r of results) {
+        const ts = parseInt(r.createdAt ?? r.timestamp ?? '0', 10);
+        if (!Number.isNaN(ts) && ts > 0)
+            createdAts.push(ts);
+    }
+    const maxCreatedAt = createdAts.length > 0 ? Math.max(...createdAts) : 0;
+    return {
+        maxCreatedAt,
+        countNewerThan(digestVersion) {
+            let n = 0;
+            for (const ca of createdAts)
+                if (ca > digestVersion)
+                    n++;
+            return n;
+        },
+    };
+}
+export async function fetchAllActiveClaims(owner, authKeyHex, encryptionKey, limit, deps, logger) {
+    let rows;
+    try {
+        rows = await deps.searchSubgraphBroadened(owner, limit, authKeyHex);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`Digest: fetchAllActiveClaims subgraph query failed: ${msg}`);
+        return '[]';
+    }
+    if (!rows || rows.length === 0)
+        return '[]';
+    const claimsOut = [];
+    for (const row of rows) {
+        if (row.isActive === false)
+            continue;
+        // Stub / tombstone blobs (encryptedBlob == "0x00") will always fail
+        // decrypt with `Encrypted data too short`. Skip pre-decrypt so we
+        // don't spin up a WASM call path per stub — the QA wallet had 7 of
+        // 25 facts as stubs, so this matters for recompile cost too.
+        if (isStubBlob(row.encryptedBlob))
+            continue;
+        try {
+            const decrypted = deps.decryptFromHex(row.encryptedBlob, encryptionKey);
+            const canonicalJson = getWasm().parseClaimOrLegacy(decrypted);
+            const claim = JSON.parse(canonicalJson);
+            // Skip infrastructure claims — digest and entity records aren't user memories.
+            if (claim.c === 'dig' || claim.c === 'ent')
+                continue;
+            claimsOut.push(claim);
+        }
+        catch {
+            // Skip un-decryptable / un-parseable rows. Don't fail the whole compilation.
+        }
+    }
+    return JSON.stringify(claimsOut);
+}
+/**
+ * Full recompile pipeline. Safe to fire-and-forget (never throws).
+ *
+ * Steps:
+ *   1. Fetch all active claims (decrypted, filtered to user-facing categories)
+ *   2. Compile via template or LLM (with template fallback)
+ *   3. Wrap as a canonical Claim and encrypt + store on-chain
+ *   4. Tombstone the previous digest (if any) so only one digest stays indexed
+ *
+ * The caller should call `tryBeginRecompile` before scheduling and
+ * `endRecompile` in a finally. This function does not touch the guard itself.
+ */
+export async function recompileDigest(input) {
+    const { mode, previousClaimId, nowUnixSeconds, deps, logger } = input;
+    try {
+        const claimsJson = await deps.fetchAllActiveClaimsFn();
+        const digestJson = await compileDigestCore({
+            claimsJson,
+            nowUnixSeconds,
+            mode,
+            llmFn: deps.llmFn,
+            logger,
+        });
+        const compiledAt = new Date(nowUnixSeconds * 1000).toISOString();
+        const canonical = buildDigestClaim({ digestJson, compiledAt });
+        await deps.storeDigestClaim(canonical, compiledAt);
+        if (previousClaimId) {
+            try {
+                await deps.tombstoneDigest(previousClaimId);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warn(`Digest: tombstone of previous ${previousClaimId.slice(0, 10)}… failed: ${msg}`);
+            }
+        }
+        logger.info(`Digest: recompiled and stored (compiledAt=${compiledAt})`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`Digest: recompile failed: ${msg}`);
+    }
+}
+/**
+ * Top-level read path helper. Decides whether to return a promptText from
+ * the latest digest, kicks off a background recompile when appropriate,
+ * and never throws.
+ *
+ * If this returns `{ promptText: null }`, the caller must fall back to the
+ * legacy individual-fact search path — digest injection is a fast path, not
+ * a replacement.
+ */
+export async function maybeInjectDigest(input) {
+    const { owner, authKeyHex, encryptionKey, mode, nowMs, loadDeps, probeDeps, recompileFn, logger, } = input;
+    if (mode === 'off') {
+        return { promptText: null, state: 'off' };
+    }
+    // Fetch the latest digest and the recency probe in parallel.
+    const [loaded, probe] = await Promise.all([
+        loadLatestDigest(owner, authKeyHex, encryptionKey, loadDeps, logger),
+        getDigestRecencyProbe(owner, authKeyHex, probeDeps),
+    ]);
+    if (!loaded) {
+        // No digest exists yet — schedule a first compile, fall back to legacy search.
+        if (!isRecompileInProgress()) {
+            recompileFn(null);
+        }
+        return { promptText: null, state: 'first-compile' };
+    }
+    const digestVersion = typeof loaded.digest.version === 'number'
+        ? loaded.digest.version
+        : parseInt(String(loaded.digest.version ?? 0), 10) || 0;
+    const compiledAt = typeof loaded.digest.compiled_at === 'string' ? loaded.digest.compiled_at : '';
+    const state = evaluateDigestState({
+        digestVersion,
+        currentMaxCreatedAt: probe.maxCreatedAt,
+        countNewClaims: probe.countNewerThan(digestVersion),
+        hoursSinceCompilation: hoursSince(compiledAt, nowMs),
+    });
+    if (state.stale && state.recompile && !isRecompileInProgress()) {
+        recompileFn(loaded.claimId);
+    }
+    const promptText = typeof loaded.digest.prompt_text === 'string' ? loaded.digest.prompt_text : null;
+    return {
+        promptText,
+        state: state.stale ? 'stale' : 'fresh',
+    };
+}

package/dist/download-ux.js

@@ -0,0 +1,63 @@
+/**
+ * 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() {
+    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 async function downloadWithUX(label, download, opts) {
+    const baseTimeoutMs = opts?.timeoutMs ?? getDownloadTimeoutMs();
+    const keepaliveMs = opts?.keepaliveMs ?? KEEPALIVE_INTERVAL_MS;
+    const maxAttempts = opts?.maxAttempts ?? MAX_DOWNLOAD_ATTEMPTS;
+    const log = opts?.log ?? ((msg) => console.error(msg));
+    const sleep = opts?.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    let lastErr = 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((_, 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.`);
+}