@totalreclaw/totalreclaw 3.3.2-rc.1 → 3.3.2-rc.3

package/CHANGELOG.md

@@ -4,32 +4,83 @@ 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).
 
-## [Unreleased]
-
-### 3.3.2-rc.1 — preinstall orphan-stage cleanup (umbrella #182 F6 / issue #190)
-
-The rc.21 fix (#126) added `cleanupInstallStagingDirs` called at plugin
-register time. That helper is too late for the re-install scenario: with
-an orphan `.openclaw-install-stage-*` sibling already present in
-`~/.openclaw/extensions/`, OpenClaw's config validator fires
-`duplicate plugin id detected; global plugin will be overridden by global
-plugin` BEFORE plugin register runs, so registration is blocked entirely
-and the helper never gets a chance to clean up. The user observes the
-warning and a plugin that silently fails to load.
-
-Fix: a new `preinstall.mjs` script runs at npm preinstall time (before
-the new install is renamed into place). It removes orphan
-`.openclaw-install-stage-*` siblings from `~/.openclaw/extensions/`
-(and `$OPENCLAW_STATE_DIR/extensions/` when set), skipping the script's
-own cwd basename so older OpenClaw versions that stage inside extensions/
-don't delete their own in-flight install. Also keeps the existing
-`.tr-partial-install` marker drop. Best-effort throughout — never throws
-or exits non-zero.
-
-Regression: `test_issue_190_preinstall_orphan_cleanup.test.ts`
-(19 assertions) covers newer-OpenClaw flow (cwd in /tmp), older-OpenClaw
-flow (cwd inside extensions/), `OPENCLAW_STATE_DIR` env override,
-no-extensions-dir fallback, and unrelated-sibling preservation.
+## [3.3.2-rc.1] — 2026-04-27
+
+Hotfix bundle for the inside-gateway agent-flow ship-stoppers caught by the
+2026-04-27 user QA against stable 3.3.1 (umbrella issue #182). The four fixes
+combined unblock the agent-driven canonical install path.
+
+### Added — filesystem load manifest (issue #186)
+
+The plugin now writes `.loaded.json` and `.error.json` into its own
+extension directory at register-time. The agent has no working CLI inside
+the gateway (issue #182 finding F1 — `openclaw plugins list` hangs in
+some Docker setups), so the manifests are the canonical filesystem signal
+that register() ran to completion AND which tools the SDK saw.
+
+- `~/.openclaw/extensions/totalreclaw/.loaded.json` —
+  `{loadedAt: <ms>, tools: [<name>...], version: <semver>}`. Written
+  synchronously at the end of `register(api)`. Captures every tool name
+  passed to `api.registerTool` during the call.
+- `~/.openclaw/extensions/totalreclaw/.error.json` —
+  `{loadedAt, error, stack?, version?}`. Written from the try/catch
+  surrounding the register() body when register() throws. Successful
+  boots clear any stale `.error.json`; failed boots preserve any prior
+  `.loaded.json` so the agent can compare timestamps.
+
+Synchronous writes only (same constraint as `registerHttpRoute` — the SDK
+freezes plugin registries the moment register() returns; an async write
+would race that freeze and the manifest could miss late tool
+registrations).
+
+Regression: `load-manifest.test.ts` (22 assertions).
+
+### Added — `totalreclaw_pair` declared in skill manifest (issue #185)
+
+The `totalreclaw_pair` tool is now advertised in `skill.json` alongside
+`totalreclaw_remember`/`recall`/`forget`/`export`/`status`/`consolidate`/
+`upgrade`/`import_from`. Previously plugin-only — if the plugin runtime
+load failed silently (e.g. dep race in #188), the tool never appeared
+in the agent's toolset and the canonical setup flow was unreachable.
+
+The skill-side declaration ensures the tool name is visible in the
+skill registry advertisement even when plugin runtime issues prevent
+binding. The implementation remains in the plugin (browser-side
+e2e-encrypted recovery-phrase flow); only the declaration moves up.
+
+### Added — atomic dependency validation in postinstall (issue #188)
+
+`postinstall.mjs` is now a real lifecycle script (replacing the inline
+`node -e` shim). After `npm install`, it require()s every critical dep
+(`@scure/bip39`, `@scure/bip39/wordlists/english.js`, `@totalreclaw/core`,
+`@totalreclaw/client`, `qrcode`, `ws`). On first-attempt failure: clears
+`node_modules`, re-runs `npm install --ignore-scripts` once, re-validates.
+If retry also fails, exits non-zero so the install surfaces the failure
+instead of writing `enabled: true` over a broken half-state.
+
+The retry loop can be skipped with `TOTALRECLAW_SKIP_POSTINSTALL_RETRY=1`
+for sandboxed CI / restricted-network environments.
+
+Phrase-safety: the script does NOT touch credentials.json, mnemonics,
+or any phrase code path. Only validates module loading and cleans
+staging directories.
+
+### Added — install-stage cleanup at install-time (issue #190)
+
+`postinstall.mjs` extends the rc.21 staging-cleanup behavior (which ran
+at register-time) to ALSO sweep `<extensions>/.openclaw-install-stage-*`
+siblings during the post-install step itself. Goal: a re-install starts
+from a clean parent dir, eliminating the
+"duplicate plugin id detected; global plugin will be overridden by global
+plugin" warning during the install. Safety: skipped when the plugin's
+parent dir is not an `extensions/` directory (dev checkouts) so no random
+siblings are deleted.
+
+Regression: `postinstall-validation.test.ts` (17 assertions) covers
+happy path, marker clearing, staging sweep, idempotent re-runs,
+unrelated-dotfile preservation, and dev-checkout safety.
+
+
 
 ### Install / runtime hygiene (issues #126, #128)
 

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.2-rc.1
+version: 3.3.2-rc.3
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/dist/fs-helpers.js

@@ -420,6 +420,107 @@ export function wipePartialInstall(pluginRootDir) {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Plugin load manifest (.loaded.json / .error.json) — 3.3.2-rc.1 #186
+// ---------------------------------------------------------------------------
+/**
+ * Filenames written into the plugin root dir at the end of register() and
+ * (on failure) from the surrounding try/catch. The presence of `.loaded.json`
+ * is the canonical filesystem signal that the plugin's register() body ran
+ * to completion AND the SDK tool/route/hook registries received calls.
+ *
+ * Acceptance criteria (issue #186):
+ *   - `cat ~/.openclaw/extensions/totalreclaw/.loaded.json` shows
+ *     `{loadedAt, tools, version}` after every successful gateway start.
+ *   - `cat ~/.openclaw/extensions/totalreclaw/.error.json` shows
+ *     `{loadedAt, error, stack}` if register() threw.
+ *   - Both are overwritten on each register() call so the agent can rely
+ *     on the timestamp matching the most recent gateway start.
+ *
+ * Why these MUST be synchronous writes (same constraint as
+ * `registerHttpRoute` per the comment in index.ts around the route
+ * registration site): the SDK loader treats register() returning as the
+ * signal to freeze the registries. An async `fs.promises.writeFile` would
+ * settle one microtask AFTER the loader has moved on, so the manifest
+ * could miss tools that registered late OR drop entirely if the gateway
+ * exits before the microtask runs. `writeFileSync` is the only safe choice.
+ */
+export const PLUGIN_LOADED_MANIFEST = '.loaded.json';
+export const PLUGIN_ERROR_MANIFEST = '.error.json';
+/**
+ * Resolve the plugin root dir from the loaded module's directory. The plugin
+ * is shipped with `dist/index.js` as the entry, so `import.meta.url` resolves
+ * to `<root>/dist/`. We walk up one level to put the manifests next to
+ * `package.json`. Defensive: if the caller already passed the root (no
+ * trailing `dist`), we still return a sensible path.
+ */
+function resolvePluginRootForManifest(pluginDir) {
+    const base = path.basename(pluginDir);
+    return base === 'dist' ? path.resolve(pluginDir, '..') : pluginDir;
+}
+/**
+ * Write the success manifest. SYNCHRONOUS — the SDK freezes the plugin
+ * registries the moment register() returns; `fs.promises.writeFile` would
+ * race that freeze and the manifest could miss late tool registrations or
+ * never land at all if the process exits before the microtask runs.
+ *
+ * Best-effort: returns `true` on success, `false` on any I/O error. Never
+ * throws — failing to write the manifest is a diagnostic loss, not a
+ * correctness loss, so we don't propagate.
+ *
+ * The manifest is written at mode 0644 (world-readable). It contains no
+ * secrets — only a timestamp, the (publicly known) tool names, and the
+ * plugin version. Cleared first so a stale `.error.json` from a previous
+ * failed boot doesn't survive a successful boot.
+ */
+export function writePluginManifest(pluginDir, manifest) {
+    try {
+        const root = resolvePluginRootForManifest(pluginDir);
+        if (!fs.existsSync(root))
+            return false;
+        const loadedPath = path.join(root, PLUGIN_LOADED_MANIFEST);
+        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
+        // Best-effort error-file cleanup — a successful boot supersedes any
+        // prior failure marker. If the unlink fails (e.g. permission), the
+        // .loaded.json timestamp still tells the agent which is current.
+        try {
+            if (fs.existsSync(errorPath))
+                fs.unlinkSync(errorPath);
+        }
+        catch {
+            // Swallow — best-effort.
+        }
+        fs.writeFileSync(loadedPath, JSON.stringify(manifest, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the error manifest. SYNCHRONOUS for the same reason as
+ * `writePluginManifest`. Called from the try/catch surrounding the
+ * register() body so the agent has a filesystem signal that the plugin
+ * registered AT LEAST attempted to load and failed in a specific way.
+ *
+ * Does NOT clear `.loaded.json` from a prior successful boot — keeping
+ * the older success marker around lets the agent see "last good boot was
+ * X, current boot failed at Y" without spelunking logs. The newer
+ * `.error.json` timestamp wins as "current state".
+ */
+export function writePluginError(pluginDir, error) {
+    try {
+        const root = resolvePluginRootForManifest(pluginDir);
+        if (!fs.existsSync(root))
+            return false;
+        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
+        fs.writeFileSync(errorPath, JSON.stringify(error, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
  * (overwrites any existing marker) and best-effort — returns `true` on