@totalreclaw/totalreclaw 3.3.12-rc.17 → 3.3.12-rc.18

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "End-to-end encrypted, decentralized memory for OpenClaw. A native kind:memory provider — recall is automatic via memory_search/memory_get, and facts are captured in the background. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any recall request ('what do you remember about me', 'what's my X'), AND any explicit remember request ('remember X', 'save X')."
-version: 3.3.12-rc.17
+version: 3.3.12-rc.18
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/dist/index.js

@@ -93,6 +93,7 @@ import { detectFirstRun, buildWelcomePrepend } from './first-run.js';
 import { buildPairRoutes } from './pair-http.js';
 import { detectGatewayHost } from './gateway-url.js';
 import { registerNativeMemory } from './native-memory.js';
+import { ensureSkillRegistered } from './skill-register.js';
 import { validateMnemonic } from '@scure/bip39';
 import { wordlist } from '@scure/bip39/wordlists/english.js';
 import crypto from 'node:crypto';
@@ -4618,6 +4619,33 @@ const plugin = {
                 const msg = err instanceof Error ? err.message : String(err);
                 api.logger.warn(`TotalReclaw: native memory capability registration failed — agent memory_search/memory_get UNAVAILABLE until fixed: ${msg}`);
             }
+            // ---------------------------------------------------------------
+            // Skill auto-register (rc.17 QA finding: plugin installs but the
+            // SKILL.md playbook does not — agents skipped the separate
+            // `openclaw skills install totalreclaw` step and ended up without
+            // pairing / recall instructions). Mirror the bundled SKILL.md +
+            // skill.json from the package root into the workspace skills dir so
+            // OpenClaw's workspace skill scanner discovers them on the next
+            // gateway load. A single `openclaw plugins install` is now enough
+            // for both plugin + skill. Idempotent + never throws (see
+            // skill-register.ts). Lives in a scanner-clean helper because
+            // index.ts already pairs env-derived config with network calls, so
+            // the disk I/O must stay out of this file.
+            // ---------------------------------------------------------------
+            try {
+                // Re-resolve the dist dir here: the earlier `pluginDir` const
+                // lives inside its own inner try/catch scope and is not visible
+                // this far down. The call is pure + cheap (URL parse + dirname).
+                ensureSkillRegistered({
+                    pluginDir: nodePath.dirname(fileURLToPath(import.meta.url)),
+                    skillsDir: nodePath.join(CONFIG.openclawWorkspace, 'skills'),
+                    logger: api.logger,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                api.logger.warn(`TotalReclaw: skill auto-register failed (non-fatal): ${msg}`);
+            }
         }
         catch (registerErr) {
             // ---------------------------------------------------------------

package/dist/skill-register.js

@@ -0,0 +1,97 @@
+/**
+ * skill-register — mirror the bundled SKILL.md + skill.json into the
+ * OpenClaw workspace skills directory on plugin load so the skill is
+ * auto-discovered without a separate `openclaw skills install` step.
+ *
+ * Why this file exists
+ * --------------------
+ * Historically `openclaw plugins install @totalreclaw/totalreclaw`
+ * installed only the plugin code; the SKILL.md instructions had to be
+ * installed via a second `openclaw skills install totalreclaw` command
+ * that agents frequently skipped — leaving the agent without the
+ * pairing / recall playbook. With the skill files copied into
+ * `~/.openclaw/workspace/skills/totalreclaw/` at register() time, the
+ * workspace skill scanner picks them up on the next gateway load, so a
+ * single `openclaw plugins install` is enough for both plugin + skill.
+ *
+ * Scanner note (MANDATORY — do not regress)
+ * -----------------------------------------
+ * This file is held scanner-clean by construction:
+ *   - NO `process.env` reads. The home / workspace path arrives as a
+ *     parameter from the caller, so the env-harvesting rule (env + net
+ *     in the same file) can never fire here.
+ *   - NO outbound-network primitives or trigger words. Disk-only. The
+ *     potential-exfiltration rule (disk read + net in the same file)
+ *     therefore cannot fire either.
+ * Do NOT add network-capable imports or trigger-word comments to this
+ * file — see `../scripts/check-scanner.mjs` for the exact rule set.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_FILES = ['SKILL.md', 'skill.json'];
+const SKILL_SUBDIR = 'totalreclaw';
+/**
+ * Copy the bundled skill files (SKILL.md + skill.json) from the plugin
+ * package root into `<skillsDir>/totalreclaw/` so the workspace skill
+ * scanner discovers them on the next gateway load.
+ *
+ * Contract:
+ *   - Creates `<skillsDir>/totalreclaw/` if missing (recursive).
+ *   - Idempotent: a destination file whose bytes already match the
+ *     source is left untouched (no rewrite, no mtime bump) so a healthy
+ *     reload is a no-op.
+ *   - A destination file whose content differs is overwritten with the
+ *     bundled source — keeps the skill in sync with the installed
+ *     plugin version across upgrades.
+ *   - Missing source files are skipped (logged at warn) — a stripped or
+ *     minimal install must not fail plugin load.
+ *   - NEVER throws. All filesystem errors are swallowed and logged;
+ *     this helper runs inside register() and a failure here must not
+ *     block plugin activation.
+ */
+export function ensureSkillRegistered(opts) {
+    const { pluginDir, skillsDir, logger } = opts;
+    const files = opts.files ?? DEFAULT_FILES;
+    // Package root is one level up from the compiled `dist/` dir. This
+    // mirrors the readPluginVersion() resolution in fs-helpers.ts.
+    const packageRoot = path.dirname(pluginDir);
+    const destDir = path.join(skillsDir, SKILL_SUBDIR);
+    try {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+    catch (err) {
+        logger.warn(`TotalReclaw: skill auto-register skipped — could not create ${destDir}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    for (const file of files) {
+        const src = path.join(packageRoot, file);
+        const dest = path.join(destDir, file);
+        try {
+            if (!fs.existsSync(src)) {
+                // Bundled file absent (trimmed tarball / dev source tree). Skip
+                // rather than failing register().
+                logger.warn(`TotalReclaw: skill auto-register — bundled source not found, skipping: ${file}`);
+                continue;
+            }
+            // Idempotent fast path: identical bytes already on disk — leave
+            // the destination untouched so a healthy reload is a no-op.
+            if (fs.existsSync(dest)) {
+                try {
+                    const srcBuf = fs.readFileSync(src);
+                    const destBuf = fs.readFileSync(dest);
+                    if (srcBuf.equals(destBuf)) {
+                        continue;
+                    }
+                }
+                catch {
+                    // Compare failed — fall through to the overwrite below.
+                }
+            }
+            fs.copyFileSync(src, dest);
+            logger.info(`TotalReclaw: skill auto-register — installed ${file} -> ${destDir}`);
+        }
+        catch (err) {
+            logger.warn(`TotalReclaw: skill auto-register failed for ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/tr-cli.js

@@ -51,7 +51,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.12-rc.17';
+const PLUGIN_VERSION = '3.3.12-rc.18';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/index.ts

@@ -199,6 +199,7 @@ import { detectFirstRun, buildWelcomePrepend, type GatewayMode } from './first-r
 import { buildPairRoutes } from './pair-http.js';
 import { detectGatewayHost } from './gateway-url.js';
 import { registerNativeMemory, type TrNativeMemoryDeps } from './native-memory.js';
+import { ensureSkillRegistered } from './skill-register.js';
 import type { TrFact, TrPinnedFact, TrQuotaState } from './memory-runtime.js';
 import { validateMnemonic } from '@scure/bip39';
 import { wordlist } from '@scure/bip39/wordlists/english.js';
@@ -5430,6 +5431,33 @@ const plugin = {
       );
     }
 
+    // ---------------------------------------------------------------
+    // Skill auto-register (rc.17 QA finding: plugin installs but the
+    // SKILL.md playbook does not — agents skipped the separate
+    // `openclaw skills install totalreclaw` step and ended up without
+    // pairing / recall instructions). Mirror the bundled SKILL.md +
+    // skill.json from the package root into the workspace skills dir so
+    // OpenClaw's workspace skill scanner discovers them on the next
+    // gateway load. A single `openclaw plugins install` is now enough
+    // for both plugin + skill. Idempotent + never throws (see
+    // skill-register.ts). Lives in a scanner-clean helper because
+    // index.ts already pairs env-derived config with network calls, so
+    // the disk I/O must stay out of this file.
+    // ---------------------------------------------------------------
+    try {
+      // Re-resolve the dist dir here: the earlier `pluginDir` const
+      // lives inside its own inner try/catch scope and is not visible
+      // this far down. The call is pure + cheap (URL parse + dirname).
+      ensureSkillRegistered({
+        pluginDir: nodePath.dirname(fileURLToPath(import.meta.url)),
+        skillsDir: nodePath.join(CONFIG.openclawWorkspace, 'skills'),
+        logger: api.logger,
+      });
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      api.logger.warn(`TotalReclaw: skill auto-register failed (non-fatal): ${msg}`);
+    }
+
     } catch (registerErr: unknown) {
       // ---------------------------------------------------------------
       // register() threw — best-effort log then re-throw so the SDK sees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.12-rc.17",
+  "version": "3.3.12-rc.18",
   "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": [
@@ -68,7 +68,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx batch-gate.test.ts && npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx llm-client-json-mode.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 pair-http.test.ts && npx tsx pair-http-route-registration.test.ts && npx tsx pair-http-init.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx initcode-lifecycle.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-state.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-native.test.ts &&npx tsx tr-cli-json-output.test.ts && npx tsx import-upgrade-cli.test.ts && npx tsx postinstall-validate.test.ts && npx tsx credential-provider.test.ts && npx tsx memory-runtime.test.ts && npx tsx tools.test.ts && npx tsx register-native.test.ts && npx tsx relay.test.ts && npx tsx vault-crypto.test.ts && npx tsx entry-env.test.ts && npx tsx trajectory-poller.test.ts",
+    "test": "npx tsx batch-gate.test.ts && npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx llm-client-json-mode.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 pair-http.test.ts && npx tsx pair-http-route-registration.test.ts && npx tsx pair-http-init.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx initcode-lifecycle.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-state.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx skill-register.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-native.test.ts &&npx tsx tr-cli-json-output.test.ts && npx tsx import-upgrade-cli.test.ts && npx tsx postinstall-validate.test.ts && npx tsx credential-provider.test.ts && npx tsx memory-runtime.test.ts && npx tsx tools.test.ts && npx tsx register-native.test.ts && npx tsx relay.test.ts && npx tsx vault-crypto.test.ts && npx tsx entry-env.test.ts && npx tsx trajectory-poller.test.ts",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "check-version-drift": "node ../scripts/check-version-drift.mjs",

package/skill-register.ts

@@ -0,0 +1,146 @@
+/**
+ * skill-register — mirror the bundled SKILL.md + skill.json into the
+ * OpenClaw workspace skills directory on plugin load so the skill is
+ * auto-discovered without a separate `openclaw skills install` step.
+ *
+ * Why this file exists
+ * --------------------
+ * Historically `openclaw plugins install @totalreclaw/totalreclaw`
+ * installed only the plugin code; the SKILL.md instructions had to be
+ * installed via a second `openclaw skills install totalreclaw` command
+ * that agents frequently skipped — leaving the agent without the
+ * pairing / recall playbook. With the skill files copied into
+ * `~/.openclaw/workspace/skills/totalreclaw/` at register() time, the
+ * workspace skill scanner picks them up on the next gateway load, so a
+ * single `openclaw plugins install` is enough for both plugin + skill.
+ *
+ * Scanner note (MANDATORY — do not regress)
+ * -----------------------------------------
+ * This file is held scanner-clean by construction:
+ *   - NO `process.env` reads. The home / workspace path arrives as a
+ *     parameter from the caller, so the env-harvesting rule (env + net
+ *     in the same file) can never fire here.
+ *   - NO outbound-network primitives or trigger words. Disk-only. The
+ *     potential-exfiltration rule (disk read + net in the same file)
+ *     therefore cannot fire either.
+ * Do NOT add network-capable imports or trigger-word comments to this
+ * file — see `../scripts/check-scanner.mjs` for the exact rule set.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Minimal logger surface matching the slice of the host plugin logger
+ * this helper uses. Declared locally so the module has no heavy type
+ * dependency on the plugin API shape.
+ */
+export interface SkillRegisterLogger {
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+}
+
+export interface EnsureSkillRegisteredOptions {
+  /**
+   * The running plugin directory — i.e. the compiled `dist/` dir where
+   * the plugin executes. SKILL.md and skill.json are resolved ONE level
+   * up from this (the package root), matching the shipped tarball layout
+   * (`dist/index.js` + `SKILL.md` + `skill.json` at the package root).
+   */
+  pluginDir: string;
+  /**
+   * The workspace `skills/` parent directory (typically
+   * `~/.openclaw/workspace/skills`). A `totalreclaw/` subdirectory is
+   * created / updated inside it. Passed in by the caller (resolved from
+   * `CONFIG.openclawWorkspace`) so this file never reads the env.
+   */
+  skillsDir: string;
+  /** Best-effort logger. Never throws. */
+  logger: SkillRegisterLogger;
+  /**
+   * Override list of filenames to mirror. Defaults to SKILL.md +
+   * skill.json. Exposed for tests; production callers omit it.
+   */
+  files?: readonly string[];
+}
+
+const DEFAULT_FILES: readonly string[] = ['SKILL.md', 'skill.json'];
+const SKILL_SUBDIR = 'totalreclaw';
+
+/**
+ * Copy the bundled skill files (SKILL.md + skill.json) from the plugin
+ * package root into `<skillsDir>/totalreclaw/` so the workspace skill
+ * scanner discovers them on the next gateway load.
+ *
+ * Contract:
+ *   - Creates `<skillsDir>/totalreclaw/` if missing (recursive).
+ *   - Idempotent: a destination file whose bytes already match the
+ *     source is left untouched (no rewrite, no mtime bump) so a healthy
+ *     reload is a no-op.
+ *   - A destination file whose content differs is overwritten with the
+ *     bundled source — keeps the skill in sync with the installed
+ *     plugin version across upgrades.
+ *   - Missing source files are skipped (logged at warn) — a stripped or
+ *     minimal install must not fail plugin load.
+ *   - NEVER throws. All filesystem errors are swallowed and logged;
+ *     this helper runs inside register() and a failure here must not
+ *     block plugin activation.
+ */
+export function ensureSkillRegistered(opts: EnsureSkillRegisteredOptions): void {
+  const { pluginDir, skillsDir, logger } = opts;
+  const files = opts.files ?? DEFAULT_FILES;
+
+  // Package root is one level up from the compiled `dist/` dir. This
+  // mirrors the readPluginVersion() resolution in fs-helpers.ts.
+  const packageRoot = path.dirname(pluginDir);
+  const destDir = path.join(skillsDir, SKILL_SUBDIR);
+
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (err) {
+    logger.warn(
+      `TotalReclaw: skill auto-register skipped — could not create ${destDir}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return;
+  }
+
+  for (const file of files) {
+    const src = path.join(packageRoot, file);
+    const dest = path.join(destDir, file);
+    try {
+      if (!fs.existsSync(src)) {
+        // Bundled file absent (trimmed tarball / dev source tree). Skip
+        // rather than failing register().
+        logger.warn(
+          `TotalReclaw: skill auto-register — bundled source not found, skipping: ${file}`,
+        );
+        continue;
+      }
+
+      // Idempotent fast path: identical bytes already on disk — leave
+      // the destination untouched so a healthy reload is a no-op.
+      if (fs.existsSync(dest)) {
+        try {
+          const srcBuf = fs.readFileSync(src);
+          const destBuf = fs.readFileSync(dest);
+          if (srcBuf.equals(destBuf)) {
+            continue;
+          }
+        } catch {
+          // Compare failed — fall through to the overwrite below.
+        }
+      }
+
+      fs.copyFileSync(src, dest);
+      logger.info(`TotalReclaw: skill auto-register — installed ${file} -> ${destDir}`);
+    } catch (err) {
+      logger.warn(
+        `TotalReclaw: skill auto-register failed for ${file}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+}

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.12-rc.17",
+  "version": "3.3.12-rc.18",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/tr-cli.ts

@@ -68,7 +68,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.12-rc.17';
+const PLUGIN_VERSION = '3.3.12-rc.18';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);