@totalreclaw/totalreclaw 3.3.5-rc.1 → 3.3.6-rc.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.6-rc.1] — 2026-05-01
+
+Patch wave from Pedro's second QA cycle on 3.3.5-rc.1.
+
+### Fixed — `/new` fallback regression from PR #175
+
+PR #175 told the agent to suggest `/new` when `/restart` returned "not authorized". Pedro QA observed that this backfires: `/new` wipes the chat context, the agent forgets it was mid-install, treats the user's next message as a fresh install request, retries from scratch, and re-trips the scanner block on the partial-install dir.
+
+Removed `/new` as a fallback for `/restart` failures from `skill/plugin/SKILL.md` and `docs/guides/openclaw-setup.md`. The only correct response when `/restart` is unauthorized is to surface the verbatim user-facing fix (`jq` + `docker restart`) and wait for `done`.
+
+### Removed — `preinstall` script (`.tr-partial-install` marker write)
+
+`skill/plugin/package.json::scripts.preinstall` was a `node -e` shell-exec that wrote a `.tr-partial-install` marker file at npm-install time. Removed entirely.
+
+Why this is safe:
+- OpenClaw's `openclaw plugins install` invokes `npm install --ignore-scripts`, so the `preinstall` script literally never fired in the canonical install path. The marker write was already dead code in the OpenClaw flow.
+- `preinstall` ran via `node -e "require('fs').writeFileSync(...)"` — a node-eval shell-exec pattern that, while not flagged by the OpenClaw scanner today (the scanner does not inspect `package.json`), was a latent risk if the scanner spec ever extends to lifecycle scripts.
+- The runtime canonical signal for partial-install detection is `dist/index.js` missing (Rule 5 in `fs-helpers.ts::detectPartialInstall`). The marker file (Rule 4) was a redundant second-line check; its absence does not weaken detection.
+- `clearPartialInstallMarker()` in `index.ts::register()` is idempotent and returns `false` when the marker is absent — no behavioral change for clean installs.
+- Helpers `writePartialInstallMarker()` / `clearPartialInstallMarker()` remain exported for backward compat and for legacy installs that may have a stale marker on disk.
+
+Tests preserved unchanged: `partial-install-detection.test.ts`, `install-reload-idempotency.test.ts`, `install-staging-cleanup.test.ts`, and `fs-helpers.test.ts` all still exercise the helper round-trip without depending on the npm script.
+
+### Added — top-level `tools` array in `skill/plugin/skill.json`
+
+Per PR #154 / #185, `totalreclaw_pair` is declared at the skill layer in `openclaw.tools` so it appears in the registry catalog independent of plugin runtime register(). Added a top-level `tools` array as a defensive companion (mirrors the `openclaw.tools` entries with a `handler: "./dist/index.js"` pointer to the runtime impl) for any tool resolver that reads top-level `tools` rather than `openclaw.tools`.
+
+Caveat: based on inspection of OpenClaw 2026.3.x reference plugins (`extensions/llm-task`, `extensions/memory-core`), OpenClaw itself does not currently parse `skill.json` at install time — tool binding happens via runtime `api.registerTool()`. The skill-layer declaration mechanism may not solve the post-install tool-binding race on its own; upstream OpenClaw work is required for an auto-refresh of the agent toolset on plugin load. Tracked separately by Pedro's research agent.
+
 ## [3.3.5-rc.1] — 2026-04-30
 
 UX bundle from Pedro's QA on 3.3.4-rc.2:

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.5-rc.1
+version: 3.3.6-rc.1
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -75,7 +75,7 @@ If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jum
 
    > Your Telegram channel needs `allowFrom` configured. Run on your host: `jq '.channels.<channel>.allowFrom = ["<your-id>"]' ~/.openclaw/openclaw.json | sponge ~/.openclaw/openclaw.json && docker restart <your-container-name>`. Substitute `<channel>` (e.g. `telegram`, `slack`), `<your-id>` (Telegram: `@username` or numeric `chat_id`; Slack: workspace member ID), and `<your-container-name>` (`docker ps` shows it). For non-Docker installs substitute `openclaw gateway restart` for the `docker restart` portion. On a managed service, ask the service's support to enable slash commands. Reply `done` after.
 
-   Then wait for `done`. Do NOT retry the install. Do NOT keep restarting. As a last-resort session-level fallback while restart is gated, try `/new` once (fresh session within the same gateway process, may pick up freshly-bound tools without a full restart).
+   Then wait for `done`. Do NOT retry the install. Do NOT keep restarting. Do NOT issue `/new` — it wipes the chat context, the agent forgets it was mid-install, and the user's next message is treated as a fresh install request which retries from scratch and re-trips the scanner block (Pedro QA, 3.3.5-rc.1).
 
    **Forbidden vocabulary** (these are anti-patterns — they show up to the user even if your transport edits them later, and they violate the silence rule):
    - "Let me check that…"

package/dist/fs-helpers.js

@@ -344,19 +344,23 @@ export function cleanupInstallStagingDirs(pluginDir, _now = Date.now) {
 // Partial-install detection (rc.22 finding #5)
 // ---------------------------------------------------------------------------
 /**
- * Marker filename written into the plugin directory at register-time. Its
- * presence means a prior install was interrupted before the plugin successfully
- * loaded — a confirmed-broken half-state that the next `openclaw plugins
- * install` retry can detect and clean.
- *
- * Conceptually the marker is dropped BEFORE npm install completes (the
- * complementary npm script removes it on success) and additionally
- * re-asserted at register-time as a second-line check. If you see this file
- * in `<extensionsDir>/totalreclaw/`, the install never reached register()
- * AND the marker drop wasn't undone.
- *
- * Constants are exported so the npm preinstall/cleanup scripts in
- * `package.json` use the same name as the runtime detector.
+ * Marker filename indicating a prior install was interrupted before the
+ * plugin successfully loaded — a confirmed-broken half-state that the next
+ * `openclaw plugins install` retry can detect and clean.
+ *
+ * 3.3.6-rc.1 (2026-05-01): the `preinstall` npm script that wrote this
+ * marker was removed. OpenClaw's `openclaw plugins install` invokes
+ * `npm install --ignore-scripts`, so the script never fired in the
+ * canonical install path anyway, and `node -e` shell-exec patterns are a
+ * latent scanner-spec risk. The runtime canonical signal for partial
+ * detection is now `dist/index.js` missing (Rule 5 in `detectPartialInstall`)
+ * — the marker (Rule 4) is a redundant second-line check that still works
+ * for legacy installs that may have a stale marker on disk.
+ *
+ * Helpers (`writePartialInstallMarker` / `clearPartialInstallMarker`) and
+ * the constant remain exported for backward compat and for any future
+ * mechanism that wants to reinstate marker writes (e.g. a runtime
+ * register-time write that is `--ignore-scripts`-safe).
  */
 export const PARTIAL_INSTALL_MARKER = '.tr-partial-install';
 /** Package name we own — used to confirm a directory is OUR plugin, not a stray. */
@@ -570,9 +574,12 @@ export function writePluginError(pluginDir, error) {
 /**
  * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
  * (overwrites any existing marker) and best-effort — returns `true` on
- * success, `false` if the dir doesn't exist or write fails. Used by the
- * `preinstall` npm script and (defensively) by the runtime if the npm
- * preinstall/cleanup script pair did not fire.
+ * success, `false` if the dir doesn't exist or write fails.
+ *
+ * 3.3.6-rc.1 (2026-05-01): the `preinstall` npm script that previously
+ * called this (via `node -e`) was removed (see `PARTIAL_INSTALL_MARKER`
+ * doc-comment). The helper remains exported for backward compat and for
+ * any future runtime register-time marker mechanism.
  */
 export function writePartialInstallMarker(pluginRootDir) {
     try {
@@ -586,10 +593,11 @@ export function writePartialInstallMarker(pluginRootDir) {
     }
 }
 /**
- * Remove the partial-install marker. Called by the `postinstall` script and
- * (defensively) at register-time once we've confirmed the load succeeded.
- * Returns `true` if a marker was removed, `false` if there was nothing to
- * remove.
+ * Remove the partial-install marker. Called at register-time once we've
+ * confirmed the load succeeded — clears any stale marker left by a legacy
+ * install, since 3.3.6-rc.1 removed the `preinstall` script that used to
+ * write fresh markers. Returns `true` if a marker was removed, `false` if
+ * there was nothing to remove.
  */
 export function clearPartialInstallMarker(pluginRootDir) {
     try {

package/dist/index.js

@@ -2476,13 +2476,17 @@ const plugin = {
                     });
                 }
                 // 3.3.1-rc.22 (rc.21 finding #5): self-heal partial-install marker.
-                // The `preinstall` npm script writes `.tr-partial-install`; clearing
-                // it has been the runtime's job since 3.3.3-rc.1 dropped postinstall.mjs
-                // (OpenClaw scanner blocked the install on the subprocess-spawn import
-                // — see 3.3.3-rc.1 PR). If we have gotten this far the loader did
-                // register us — meaning the install succeeded enough to be useful —
-                // so any lingering marker is stale. Clear it so the next retry's
-                // detector does not see a false positive.
+                // Clearing the marker has been the runtime's job since 3.3.3-rc.1
+                // dropped postinstall.mjs (OpenClaw scanner blocked the install on
+                // the subprocess-spawn import — see 3.3.3-rc.1 PR). 3.3.6-rc.1
+                // additionally dropped the `preinstall` npm script that wrote the
+                // marker (npm install --ignore-scripts meant it never fired in the
+                // canonical install path anyway, and `node -e` shell-exec is a
+                // latent scanner-spec risk). The clear call here remains valid for
+                // legacy installs that may have a stale marker on disk. If we have
+                // gotten this far the loader did register us — meaning the install
+                // succeeded enough to be useful — so any lingering marker is stale.
+                // Clear it so the next retry's detector does not see a false positive.
                 //
                 // 3.3.1-rc.22 (rc.21 finding #6) — gateway/reload upstream caveat:
                 // OpenClaw's config-watcher fires `gateway/reload` when

package/fs-helpers.ts

@@ -393,19 +393,23 @@ export function cleanupInstallStagingDirs(
 // ---------------------------------------------------------------------------
 
 /**
- * Marker filename written into the plugin directory at register-time. Its
- * presence means a prior install was interrupted before the plugin successfully
- * loaded — a confirmed-broken half-state that the next `openclaw plugins
- * install` retry can detect and clean.
+ * Marker filename indicating a prior install was interrupted before the
+ * plugin successfully loaded — a confirmed-broken half-state that the next
+ * `openclaw plugins install` retry can detect and clean.
  *
- * Conceptually the marker is dropped BEFORE npm install completes (the
- * complementary npm script removes it on success) and additionally
- * re-asserted at register-time as a second-line check. If you see this file
- * in `<extensionsDir>/totalreclaw/`, the install never reached register()
- * AND the marker drop wasn't undone.
+ * 3.3.6-rc.1 (2026-05-01): the `preinstall` npm script that wrote this
+ * marker was removed. OpenClaw's `openclaw plugins install` invokes
+ * `npm install --ignore-scripts`, so the script never fired in the
+ * canonical install path anyway, and `node -e` shell-exec patterns are a
+ * latent scanner-spec risk. The runtime canonical signal for partial
+ * detection is now `dist/index.js` missing (Rule 5 in `detectPartialInstall`)
+ * — the marker (Rule 4) is a redundant second-line check that still works
+ * for legacy installs that may have a stale marker on disk.
  *
- * Constants are exported so the npm preinstall/cleanup scripts in
- * `package.json` use the same name as the runtime detector.
+ * Helpers (`writePartialInstallMarker` / `clearPartialInstallMarker`) and
+ * the constant remain exported for backward compat and for any future
+ * mechanism that wants to reinstate marker writes (e.g. a runtime
+ * register-time write that is `--ignore-scripts`-safe).
  */
 export const PARTIAL_INSTALL_MARKER = '.tr-partial-install';
 
@@ -666,9 +670,12 @@ export function writePluginError(
 /**
  * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
  * (overwrites any existing marker) and best-effort — returns `true` on
- * success, `false` if the dir doesn't exist or write fails. Used by the
- * `preinstall` npm script and (defensively) by the runtime if the npm
- * preinstall/cleanup script pair did not fire.
+ * success, `false` if the dir doesn't exist or write fails.
+ *
+ * 3.3.6-rc.1 (2026-05-01): the `preinstall` npm script that previously
+ * called this (via `node -e`) was removed (see `PARTIAL_INSTALL_MARKER`
+ * doc-comment). The helper remains exported for backward compat and for
+ * any future runtime register-time marker mechanism.
  */
 export function writePartialInstallMarker(pluginRootDir: string): boolean {
   try {
@@ -681,10 +688,11 @@ export function writePartialInstallMarker(pluginRootDir: string): boolean {
 }
 
 /**
- * Remove the partial-install marker. Called by the `postinstall` script and
- * (defensively) at register-time once we've confirmed the load succeeded.
- * Returns `true` if a marker was removed, `false` if there was nothing to
- * remove.
+ * Remove the partial-install marker. Called at register-time once we've
+ * confirmed the load succeeded — clears any stale marker left by a legacy
+ * install, since 3.3.6-rc.1 removed the `preinstall` script that used to
+ * write fresh markers. Returns `true` if a marker was removed, `false` if
+ * there was nothing to remove.
  */
 export function clearPartialInstallMarker(pluginRootDir: string): boolean {
   try {

package/index.ts

@@ -3043,13 +3043,17 @@ const plugin = {
       }
 
       // 3.3.1-rc.22 (rc.21 finding #5): self-heal partial-install marker.
-      // The `preinstall` npm script writes `.tr-partial-install`; clearing
-      // it has been the runtime's job since 3.3.3-rc.1 dropped postinstall.mjs
-      // (OpenClaw scanner blocked the install on the subprocess-spawn import
-      // — see 3.3.3-rc.1 PR). If we have gotten this far the loader did
-      // register us — meaning the install succeeded enough to be useful —
-      // so any lingering marker is stale. Clear it so the next retry's
-      // detector does not see a false positive.
+      // Clearing the marker has been the runtime's job since 3.3.3-rc.1
+      // dropped postinstall.mjs (OpenClaw scanner blocked the install on
+      // the subprocess-spawn import — see 3.3.3-rc.1 PR). 3.3.6-rc.1
+      // additionally dropped the `preinstall` npm script that wrote the
+      // marker (npm install --ignore-scripts meant it never fired in the
+      // canonical install path anyway, and `node -e` shell-exec is a
+      // latent scanner-spec risk). The clear call here remains valid for
+      // legacy installs that may have a stale marker on disk. If we have
+      // gotten this far the loader did register us — meaning the install
+      // succeeded enough to be useful — so any lingering marker is stale.
+      // Clear it so the next retry's detector does not see a false positive.
       //
       // 3.3.1-rc.22 (rc.21 finding #6) — gateway/reload upstream caveat:
       // OpenClaw's config-watcher fires `gateway/reload` when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.5-rc.1",
+  "version": "3.3.6-rc.1",
   "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": [
@@ -70,7 +70,6 @@
     "check-version-drift": "node ../scripts/check-version-drift.mjs",
     "check-url-binding": "node ../scripts/check-url-binding.mjs",
     "sync-version": "node ../scripts/sync-version.mjs",
-    "preinstall": "node -e \"try{require('fs').writeFileSync('.tr-partial-install','');}catch{}\"",
     "prepack": "npm run build",
     "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs && node ../scripts/check-url-binding.mjs --release-type=${TOTALRECLAW_RELEASE_TYPE:-rc}"
   },

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.5-rc.1",
+  "version": "3.3.6-rc.1",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",
@@ -15,6 +15,131 @@
     "agent-memory",
     "persistent-context"
   ],
+  "tools": [
+    {
+      "name": "totalreclaw_pair",
+      "description": "Set up the user's TotalReclaw account (encrypted, browser-side recovery-phrase generation or import). Returns an account-setup URL, a 6-digit PIN, and an ASCII QR code that the agent relays to the user. The recovery phrase is generated/entered in the BROWSER and uploaded end-to-end encrypted to this gateway — it NEVER touches the LLM provider or the chat transcript. This is the canonical agent-facilitated account-setup surface. Tool name kept for backward compatibility — function-wise this is the account-setup tool.",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "mode": {
+          "type": "string",
+          "required": false,
+          "enum": ["generate", "import"],
+          "default": "generate",
+          "description": "\"generate\" = browser will create a NEW recovery phrase. \"import\" = browser will accept an EXISTING phrase pasted by the user in their browser (never through chat)."
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_remember",
+      "description": "Store a new fact or preference in long-term memory",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "text": {
+          "type": "string",
+          "required": true,
+          "description": "The fact or information to remember"
+        },
+        "type": {
+          "type": "string",
+          "required": false,
+          "enum": ["fact", "preference", "decision", "episodic", "goal"],
+          "default": "fact",
+          "description": "Type of memory"
+        },
+        "importance": {
+          "type": "integer",
+          "required": false,
+          "min": 1,
+          "max": 10,
+          "description": "Importance score 1-10. Default: auto-detected by LLM"
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_recall",
+      "description": "Search and retrieve relevant memories from long-term storage",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Natural language query to search memories"
+        },
+        "k": {
+          "type": "integer",
+          "required": false,
+          "default": 8,
+          "max": 20,
+          "description": "Number of results to return"
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_forget",
+      "description": "Delete a specific fact from memory",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "factId": {
+          "type": "string",
+          "required": true,
+          "description": "UUID of the fact to delete"
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_export",
+      "description": "Export all stored memories in plaintext format",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "format": {
+          "type": "string",
+          "required": false,
+          "enum": ["json", "markdown"],
+          "default": "json",
+          "description": "Export format"
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_status",
+      "description": "Check billing and subscription status, including quota usage and upgrade options",
+      "handler": "./dist/index.js",
+      "parameters": {}
+    },
+    {
+      "name": "totalreclaw_upgrade",
+      "description": "Get a checkout URL to upgrade to TotalReclaw Pro (unlimited memories on Gnosis mainnet)",
+      "handler": "./dist/index.js",
+      "parameters": {}
+    },
+    {
+      "name": "totalreclaw_import_from",
+      "description": "Import memories from other AI memory tools (Mem0, MCP Memory Server) into TotalReclaw",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "source": {
+          "type": "string",
+          "required": true,
+          "enum": ["mem0", "mcp-memory"],
+          "description": "Source system to import from"
+        }
+      }
+    },
+    {
+      "name": "totalreclaw_consolidate",
+      "description": "Scan all stored memories and merge near-duplicates, keeping the most important/recent version",
+      "handler": "./dist/index.js",
+      "parameters": {
+        "dry_run": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Preview consolidation without deleting"
+        }
+      }
+    }
+  ],
   "openclaw": {
     "minVersion": "0.1.0",
     "maxVersion": "1.0.0",