@totalreclaw/totalreclaw 3.3.1-rc.2 → 3.3.1-rc.21

package/dist/tool-gating.js

@@ -0,0 +1,58 @@
+/**
+ * Tool gating predicate for 3.2.0 — the `before_tool_call` hook in index.ts
+ * delegates to this module so the logic is testable without standing up a
+ * full OpenClaw plugin host.
+ *
+ * Scope: the 3.2.0 state machine has two states (`fresh`, `active`). Memory
+ * tools are blocked when state is anything other than `active`. Billing +
+ * setup-adjacent tools remain usable — users need to be able to upgrade,
+ * migrate, and start onboarding before their vault is active.
+ *
+ * This module imports ONLY types + the state resolver. No I/O beyond what
+ * `resolveOnboardingState` already does; no network; no env reads.
+ */
+/**
+ * Tool names gated on `state=active`. Keep in sync with the actual
+ * `registerTool` calls in `index.ts`. Anything NOT in this set is always
+ * callable (e.g. totalreclaw_upgrade, totalreclaw_migrate,
+ * totalreclaw_onboarding_start, totalreclaw_setup).
+ */
+export const GATED_TOOL_NAMES = Object.freeze([
+    'totalreclaw_remember',
+    'totalreclaw_recall',
+    'totalreclaw_forget',
+    'totalreclaw_export',
+    'totalreclaw_status',
+    'totalreclaw_consolidate',
+    'totalreclaw_pin',
+    'totalreclaw_unpin',
+    'totalreclaw_retype',
+    'totalreclaw_set_scope',
+    'totalreclaw_import_from',
+    'totalreclaw_import_batch',
+]);
+/**
+ * Decide whether a specific tool call should be blocked given the current
+ * onboarding state. Does not read any files — caller resolves state first
+ * (that lets tests stub state without touching disk).
+ */
+export function decideToolGate(toolName, state) {
+    if (!toolName)
+        return { block: false };
+    if (!GATED_TOOL_NAMES.includes(toolName))
+        return { block: false };
+    if (state?.onboardingState === 'active')
+        return { block: false };
+    return {
+        block: true,
+        blockReason: 'TotalReclaw onboarding required. Run `openclaw totalreclaw onboard` ' +
+            'in a terminal (or call the `totalreclaw_onboarding_start` tool for ' +
+            'details). Memory tools are gated until the user completes setup.',
+    };
+}
+/**
+ * Convenience predicate — useful for tests + documentation.
+ */
+export function isGatedToolName(toolName) {
+    return GATED_TOOL_NAMES.includes(toolName);
+}

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/fs-helpers.ts

@@ -56,6 +56,15 @@ export interface CredentialsFile {
   mnemonic?: string;
   /** Alias for `mnemonic`, accepted on read only. */
   recovery_phrase?: string;
+  /**
+   * Smart Account (scope) address derived from the mnemonic. Persisted at
+   * pair-finish so users + tools (`totalreclaw_status`) can read it before
+   * any on-chain write. Internal#130 — lazy SA derivation previously left
+   * the user blind to their scope address until first-write.
+   *
+   * Format: lowercase 0x-prefixed 40-hex-char address. Public, non-secret.
+   */
+  scope_address?: string;
   firstRunAnnouncementShown?: boolean;
   [extra: string]: unknown;
 }
@@ -107,6 +116,38 @@ export function ensureMemoryHeaderFile(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Plugin version — 3.3.1-rc.3 helper for RC gating
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the plugin's own version string from `package.json`.
+ *
+ * Behaviour:
+ *   - Resolves `package.json` next to the caller-provided directory
+ *     (typically `path.dirname(fileURLToPath(import.meta.url))` from the
+ *     caller).
+ *   - Returns the `version` field, or `null` on any I/O / parse error.
+ *
+ * Used by the RC-gated `totalreclaw_report_qa_bug` tool registration in
+ * `index.ts`: if the version contains `-rc.`, register the tool; if not,
+ * skip it entirely so stable users never see it.
+ *
+ * Scanner-safe: pure filesystem. No outbound-request word markers in this
+ * helper — see the file-header guardrail.
+ */
+export function readPluginVersion(packageJsonDir: string): string | null {
+  try {
+    const pkgPath = path.join(packageJsonDir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return null;
+    const raw = fs.readFileSync(pkgPath, 'utf-8');
+    const parsed = JSON.parse(raw) as { version?: string };
+    return typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // credentials.json load / write / delete
 // ---------------------------------------------------------------------------
@@ -220,6 +261,89 @@ export function deleteFileIfExists(filePath: string): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Install-staging cleanup (issue #126 — rc.20 finding F3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clean up `.openclaw-install-stage-*` sibling directories left behind by
+ * an interrupted `openclaw plugins install` run.
+ *
+ * Background
+ * ----------
+ * `openclaw plugins install @totalreclaw/totalreclaw` extracts the npm
+ * tarball into a staging directory named
+ * `<extensionsDir>/.openclaw-install-stage-XXXXXX/` and then renames it
+ * to `<extensionsDir>/totalreclaw/` on success. If the install is
+ * interrupted partway through (e.g. an auto-gateway-restart triggered by
+ * the same install kills the process — see rc.20 QA finding F3), the
+ * staging dir survives. On the next gateway start, OpenClaw's plugin
+ * loader auto-discovers BOTH directories — the real `totalreclaw/` and
+ * the orphaned `.openclaw-install-stage-XXXXXX/` — and registers two
+ * copies of the plugin. Hooks fire twice, the user sees a duplicate
+ * `totalreclaw` row in `openclaw plugins list`, and the gateway log
+ * spams a duplicate-plugin-id warning every cycle.
+ *
+ * Fix scope: best-effort cleanup driven by the plugin itself at register
+ * time. We resolve the extensions dir as the parent of the loaded
+ * plugin's own directory, scan for `.openclaw-install-stage-*` siblings,
+ * and recursively remove each one. If anything fails (permission,
+ * race with a concurrent install), we swallow the error — the existing
+ * loader-warning behavior is no worse than before.
+ *
+ * Returns the list of staging-dir paths that were successfully removed.
+ * Callers may log this for ops visibility. Empty list on a clean install.
+ *
+ * Parameters
+ * ----------
+ * @param pluginDir  Absolute path to the loaded plugin's directory
+ *                   (typically `<extensionsDir>/totalreclaw/dist`). The
+ *                   helper walks up to the parent that holds sibling
+ *                   plugin directories (the `extensions/` root).
+ * @param _now       Optional clock injector for testing — defaults to
+ *                   Date.now().
+ */
+export function cleanupInstallStagingDirs(
+  pluginDir: string,
+  _now: () => number = Date.now,
+): string[] {
+  const removed: string[] = [];
+  try {
+    // pluginDir is `<extensionsDir>/totalreclaw/dist` after build, so the
+    // siblings live two levels up. Resolve both candidates so the helper
+    // works regardless of whether the caller passes the package root or
+    // its `dist/` subdir.
+    const candidates = [
+      path.resolve(pluginDir, '..'),       // <extensionsDir>/totalreclaw → siblings dir if pluginDir is `dist`
+      path.resolve(pluginDir, '..', '..'), // <extensionsDir>/             → siblings dir if pluginDir is package root
+    ];
+
+    for (const extensionsDir of candidates) {
+      let entries: string[];
+      try {
+        entries = fs.readdirSync(extensionsDir);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.startsWith('.openclaw-install-stage-')) continue;
+        const target = path.join(extensionsDir, name);
+        try {
+          const st = fs.lstatSync(target);
+          if (!st.isDirectory()) continue;
+          fs.rmSync(target, { recursive: true, force: true });
+          removed.push(target);
+        } catch {
+          // Best-effort — skip unreadable / racy entries.
+        }
+      }
+    }
+  } catch {
+    // Best-effort — never crash plugin init on cleanup failure.
+  }
+  return removed;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-bootstrap of credentials.json (3.1.0 first-run UX)
 // ---------------------------------------------------------------------------

package/gateway-url.ts

@@ -126,27 +126,66 @@ function shouldSkipIface(name: string): boolean {
   return SKIP_IFACE_PREFIXES.some((p) => lower.startsWith(p));
 }
 
+/**
+ * Docker container internal IP detection — issue #110 fix 4.
+ *
+ * From INSIDE a Docker container, `eth0` carries the container's bridge IP
+ * (e.g. `172.18.0.2`). That IP is reachable from other containers on the
+ * SAME Docker network but NOT from the host browser, the user's phone, or
+ * any external device. Surfacing it as the pairing URL produces a hard-
+ * dead user experience: "scan QR" yields connection-refused.
+ *
+ * Docker default-bridge ranges:
+ *   - 172.17.0.0/16 — `bridge` (default)
+ *   - 172.18.0.0/16 .. 172.31.0.0/16 — user-defined networks
+ *
+ * We use the conservative test: 172.16.0.0/12 (the full RFC-1918 172.x
+ * range, which is what Docker draws from). If the host is clearly Docker
+ * (`/.dockerenv`), we treat 172.16-31.x.x AS Docker-internal and skip it.
+ *
+ * Outside Docker, 172.16.x.x can be a legitimate corporate LAN, so we
+ * only apply the rule when we have positive Docker evidence.
+ */
+export function isDockerInternalIp(addr: string): boolean {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(addr)) return false;
+  const parts = addr.split('.').map((p) => Number.parseInt(p, 10));
+  if (parts[0] !== 172) return false;
+  return parts[1] >= 16 && parts[1] <= 31;
+}
+
 /**
  * Pick the first non-loopback, non-virtual IPv4 address. Returns null if
  * none found (headless VPS with only lo + tailscale, for example).
+ *
+ * issue #110 fix 4: when the host is detected as Docker (caller passes
+ * `isDocker: true`), skip Docker-bridge IPs in the 172.16/12 range — they
+ * are container-internal and useless for any external browser. Returning
+ * null from this function in that scenario lets `buildPairingUrl` fall
+ * through to the localhost-with-relay-fallback warning rather than handing
+ * the user a dead URL.
  */
 export function detectLanHost(options?: {
   /** Override os.networkInterfaces for tests. */
   networkInterfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+  /** True when the host is Docker — skips 172.16/12 bridge IPs. */
+  isDocker?: boolean;
 }): DetectedGatewayHost | null {
   const nif = (options?.networkInterfaces ?? os.networkInterfaces)();
   for (const [name, addrs] of Object.entries(nif)) {
     if (shouldSkipIface(name)) continue;
     if (!addrs) continue;
     for (const a of addrs) {
-      if (a.family === 'IPv4' && !a.internal) {
-        return {
-          kind: 'lan',
-          host: a.address,
-          tls: false,
-          note: `LAN IPv4 on interface ${name} — only reachable from the same network.`,
-        };
-      }
+      if (a.family !== 'IPv4' || a.internal) continue;
+      // issue #110 fix 4 — Docker container internal IP is unreachable
+      // from any external browser. Skip it so the caller falls back to
+      // the relay-brokered URL.
+      if (options?.isDocker && isDockerInternalIp(a.address)) continue;
+      return {
+        kind: 'lan',
+        host: a.address,
+        tls: false,
+        note: `LAN IPv4 on interface ${name} — only reachable from the same network.`,
+      };
     }
   }
   return null;
@@ -162,13 +201,22 @@ export function detectLanHost(options?: {
  *
  * Sync: no I/O, no subprocess, no network. Safe in sync callers like
  * `buildPairingUrl` in index.ts.
+ *
+ * issue #110 fix 4: the `isDocker` option, when true, skips the 172.16/12
+ * Docker-bridge range during LAN detection. The caller (index.ts) passes
+ * `isRunningInDocker()` so we don't surface a container-internal IP that
+ * no external browser can reach.
  */
 export function detectGatewayHost(options?: {
   networkInterfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+  isDocker?: boolean;
 }): DetectedGatewayHost | null {
   const ts = detectTailscaleHost({ networkInterfaces: options?.networkInterfaces });
   if (ts) return ts;
-  const lan = detectLanHost({ networkInterfaces: options?.networkInterfaces });
+  const lan = detectLanHost({
+    networkInterfaces: options?.networkInterfaces,
+    isDocker: options?.isDocker,
+  });
   if (lan) return lan;
   return null;
 }