@totalreclaw/totalreclaw 3.3.9-rc.1 → 3.3.9-rc.2

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.9-rc.2] — 2026-05-02
+
+Patch release fixing the two OpenClaw 2026.5.x compatibility blockers discovered during 3.3.9-rc.1 auto-QA ([umbrella #224](https://github.com/p-diogo/totalreclaw-internal/issues/224)).
+
+### Fixed
+
+- **Finding #1 — memory slot not auto-assigned on install ([#225](https://github.com/p-diogo/totalreclaw-internal/issues/225)):** OpenClaw 2026.5.x introduced memory-slot exclusivity — a `kind: memory` plugin must explicitly claim `plugins.slots.memory` in `openclaw.json` or it is silently disabled ("memory slot set to memory-core"). Previously required manual config edit with no user-visible error. The plugin's `register()` now calls `patchOpenClawConfig()` at startup, which idempotently writes `plugins.slots.memory = "totalreclaw"` if absent. If the file was patched, a warn is emitted asking for a gateway restart.
+
+- **Finding #2 — conversation hooks blocked by missing `allowConversationAccess` ([#226](https://github.com/p-diogo/totalreclaw-internal/issues/226)):** OpenClaw 2026.5.x requires `plugins.entries.totalreclaw.hooks.allowConversationAccess = true` for non-bundled plugins to receive `agent_end` and `before_agent_start` hooks. Without it, auto-extraction and recall injection are silently disabled — the hooks simply never fire. The same `patchOpenClawConfig()` call now idempotently writes this key alongside the slot claim.
+
+### Implementation notes
+
+- `patchOpenClawConfig()` added to `fs-helpers.ts` — synchronous, best-effort, scanner-safe (pure `node:fs` / `node:path`, no network markers).
+- Called early in `register()` (after install-staging cleanup, before LLM init). Idempotent — if both keys are already correct the file is not touched.
+- Results: `'patched'` (file mutated — warn + restart instruction), `'unchanged'` (no-op), `'skipped'` (no `openclaw.json` found — non-OpenClaw host), `'error'` (parse/write failure — warn with manual instructions).
+- **Restart required when patched:** OpenClaw reads `openclaw.json` at startup. When this runs on the FIRST boot after install, it patches the file and emits the restart warning. After the user restarts, the second boot picks up the keys and all hooks fire normally.
+
 ## [3.3.9-rc.1] — 2026-05-02
 
 Pedro's QA on 3.3.8-rc.1 (Telegram → canonical OpenClaw 2026.5.2) revealed five issues that all stem from the same architectural problem — TotalReclaw's tools registered via `api.registerTool()` are blocked by OpenClaw 2026.5.2's tool-policy strip race (issue #223, filed upstream). Each release we ship adds a fix for one gate, hits another. 3.3.9-rc.1 pivots to hybrid-primary: the `tr` CLI is now the PRIMARY path. Native tools are kept for back-compat only.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.9-rc.1
+version: 3.3.9-rc.2
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/dist/fs-helpers.js

@@ -929,3 +929,85 @@ export function resolveOnboardingState(credentialsPath, statePath) {
     writeOnboardingState(statePath, next);
     return next;
 }
+/**
+ * Auto-patch `~/.openclaw/openclaw.json` with the two entries required by
+ * OpenClaw 2026.5.x for `kind: memory` plugins (issues #225 + #226):
+ *
+ *   1. `plugins.slots.memory = "totalreclaw"`
+ *      Claim the memory slot so the plugin loads instead of deferring to
+ *      the built-in `memory-core` tenant.
+ *
+ *   2. `plugins.entries.totalreclaw.hooks.allowConversationAccess = true`
+ *      Grant the plugin access to `agent_end` and `before_agent_start`
+ *      hooks. Without this flag OpenClaw 2026.5.x silently blocks both
+ *      hooks for non-bundled plugins, disabling auto-extraction and
+ *      recall injection.
+ *
+ * Design constraints
+ * ------------------
+ * - SYNCHRONOUS — called during register() which must be sync.
+ * - IDEMPOTENT — reads existing values before deciding to write; no-ops
+ *   when both keys are already correct.
+ * - BEST-EFFORT — all errors are swallowed; the plugin keeps loading even
+ *   if the patch fails. The caller logs an actionable warning.
+ * - SCANNER-SAFE — pure `node:fs` / `node:path`; no outbound markers.
+ *
+ * Restart semantics
+ * -----------------
+ * OpenClaw reads `openclaw.json` at gateway startup, not dynamically.
+ * When `patchOpenClawConfig` writes new keys during the CURRENT gateway
+ * boot, the keys take effect ONLY after the gateway is restarted. The
+ * plugin must tell the user via `api.logger.warn` so they know to run
+ * `/totalreclaw-restart` or restart the gateway manually.
+ *
+ * @param configPath  Absolute path to `openclaw.json`.
+ *                    Defaults to `<home>/.openclaw/openclaw.json`.
+ */
+export function patchOpenClawConfig(configPath) {
+    const home = process.env.HOME ?? '/home/node';
+    const target = configPath ?? path.join(home, '.openclaw', 'openclaw.json');
+    // `'skipped'` when the config file is absent — this host may not be
+    // running OpenClaw, or may use a non-standard config location.
+    if (!fs.existsSync(target))
+        return 'skipped';
+    try {
+        const raw = fs.readFileSync(target, 'utf-8');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const cfg = JSON.parse(raw);
+        // Ensure the `plugins` key exists.
+        if (typeof cfg.plugins !== 'object' || cfg.plugins === null) {
+            cfg.plugins = {};
+        }
+        let mutated = false;
+        // --- Fix #1: plugins.slots.memory = "totalreclaw" ---
+        if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
+            cfg.plugins.slots = {};
+        }
+        if (cfg.plugins.slots.memory !== 'totalreclaw') {
+            cfg.plugins.slots.memory = 'totalreclaw';
+            mutated = true;
+        }
+        // --- Fix #2: plugins.entries.totalreclaw.hooks.allowConversationAccess = true ---
+        if (typeof cfg.plugins.entries !== 'object' || cfg.plugins.entries === null) {
+            cfg.plugins.entries = {};
+        }
+        if (typeof cfg.plugins.entries.totalreclaw !== 'object' || cfg.plugins.entries.totalreclaw === null) {
+            cfg.plugins.entries.totalreclaw = {};
+        }
+        if (typeof cfg.plugins.entries.totalreclaw.hooks !== 'object' || cfg.plugins.entries.totalreclaw.hooks === null) {
+            cfg.plugins.entries.totalreclaw.hooks = {};
+        }
+        if (cfg.plugins.entries.totalreclaw.hooks.allowConversationAccess !== true) {
+            cfg.plugins.entries.totalreclaw.hooks.allowConversationAccess = true;
+            mutated = true;
+        }
+        if (!mutated)
+            return 'unchanged';
+        // Write back with 2-space indent to match OpenClaw's own write style.
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n');
+        return 'patched';
+    }
+    catch {
+        return 'error';
+    }
+}

package/dist/index.js

@@ -66,7 +66,7 @@ import { PluginHotCache } from './hot-cache-wrapper.js';
 import { CONFIG, setRecoveryPhraseOverride } from './config.js';
 import { buildRelayHeaders } from './relay-headers.js';
 import { readBillingCache, writeBillingCache, BILLING_CACHE_PATH, } from './billing-cache.js';
-import { ensureMemoryHeaderFile, loadCredentialsJson, writeCredentialsJson, deleteCredentialsFile, isRunningInDocker, deleteFileIfExists, resolveOnboardingState, writeOnboardingState, readPluginVersion, cleanupInstallStagingDirs, clearPartialInstallMarker, writePluginManifest, writePluginError, readPluginLoadedManifest, } from './fs-helpers.js';
+import { ensureMemoryHeaderFile, loadCredentialsJson, writeCredentialsJson, deleteCredentialsFile, isRunningInDocker, deleteFileIfExists, resolveOnboardingState, writeOnboardingState, readPluginVersion, cleanupInstallStagingDirs, clearPartialInstallMarker, patchOpenClawConfig, writePluginManifest, writePluginError, readPluginLoadedManifest, } from './fs-helpers.js';
 import { isRcBuild } from './qa-bug-report.js';
 import { decideToolGate, isGatedToolName } from './tool-gating.js';
 import { resolveRestartAuth, rejectMessageFor, } from './restart-auth.js';
@@ -2531,6 +2531,45 @@ const plugin = {
                 catch {
                     // Best-effort. Helper logs internally and never throws.
                 }
+                // 3.3.9-rc.2 (issues #225 + #226): auto-patch openclaw.json for
+                // OpenClaw 2026.5.x. Two required config keys were not auto-applied
+                // by `openclaw plugins install` in 2026.5.x:
+                //
+                //   1. plugins.slots.memory = "totalreclaw"
+                //      OpenClaw 2026.5.x introduced memory-slot exclusivity — a
+                //      memory-kind plugin MUST explicitly claim the slot or it is
+                //      silently disabled (no error shown; `openclaw plugins inspect`
+                //      shows "memory slot set to memory-core"). #225.
+                //
+                //   2. plugins.entries.totalreclaw.hooks.allowConversationAccess = true
+                //      Non-bundled plugins in 2026.5.x require this flag to receive
+                //      agent_end and before_agent_start hooks. Without it, auto-
+                //      extraction and recall injection are silently disabled. #226.
+                //
+                // The patch is idempotent — if both keys are already correct the
+                // file is not touched. When the file IS mutated a restart is
+                // required for the new keys to take effect (OpenClaw reads
+                // openclaw.json at startup, not dynamically). We emit a warn so
+                // the user and ops scripts know to trigger a restart.
+                try {
+                    const patchResult = patchOpenClawConfig();
+                    if (patchResult === 'patched') {
+                        api.logger.warn('TotalReclaw: updated openclaw.json with required 2026.5.x keys ' +
+                            '(plugins.slots.memory + hooks.allowConversationAccess). ' +
+                            'Gateway restart required for the changes to take effect. ' +
+                            'Run `/totalreclaw-restart` or restart the gateway manually.');
+                    }
+                    else if (patchResult === 'error') {
+                        api.logger.warn('TotalReclaw: failed to auto-patch openclaw.json for OpenClaw 2026.5.x ' +
+                            'compatibility. If memory hooks are silently disabled, add these keys ' +
+                            'manually: plugins.slots.memory="totalreclaw" and ' +
+                            'plugins.entries.totalreclaw.hooks.allowConversationAccess=true.');
+                    }
+                    // 'unchanged' and 'skipped' are silent — no log needed.
+                }
+                catch {
+                    // Best-effort — never let config-patch failure block plugin load.
+                }
             }
             catch {
                 rcMode = false;

package/fs-helpers.ts

@@ -1126,3 +1126,111 @@ export function resolveOnboardingState(
   writeOnboardingState(statePath, next);
   return next;
 }
+
+// ---------------------------------------------------------------------------
+// OpenClaw 2026.5.x config auto-patch (3.3.9-rc.2 — issues #225 + #226)
+// ---------------------------------------------------------------------------
+
+/**
+ * Outcome of `patchOpenClawConfig`.
+ *  - `'patched'`   — one or more required keys were missing; file was updated.
+ *                    Caller must log a message telling the user to restart.
+ *  - `'unchanged'` — all required keys already present; no write.
+ *  - `'skipped'`   — config file not found (not an OpenClaw host, or pre-2026
+ *                    version that uses a different config path). Caller is safe
+ *                    to ignore.
+ *  - `'error'`     — file exists but read/parse/write failed. Caller logs
+ *                    warn and continues — the plugin still loads, the user
+ *                    must apply the keys manually.
+ */
+export type OpenClawConfigPatchResult = 'patched' | 'unchanged' | 'skipped' | 'error';
+
+/**
+ * Auto-patch `~/.openclaw/openclaw.json` with the two entries required by
+ * OpenClaw 2026.5.x for `kind: memory` plugins (issues #225 + #226):
+ *
+ *   1. `plugins.slots.memory = "totalreclaw"`
+ *      Claim the memory slot so the plugin loads instead of deferring to
+ *      the built-in `memory-core` tenant.
+ *
+ *   2. `plugins.entries.totalreclaw.hooks.allowConversationAccess = true`
+ *      Grant the plugin access to `agent_end` and `before_agent_start`
+ *      hooks. Without this flag OpenClaw 2026.5.x silently blocks both
+ *      hooks for non-bundled plugins, disabling auto-extraction and
+ *      recall injection.
+ *
+ * Design constraints
+ * ------------------
+ * - SYNCHRONOUS — called during register() which must be sync.
+ * - IDEMPOTENT — reads existing values before deciding to write; no-ops
+ *   when both keys are already correct.
+ * - BEST-EFFORT — all errors are swallowed; the plugin keeps loading even
+ *   if the patch fails. The caller logs an actionable warning.
+ * - SCANNER-SAFE — pure `node:fs` / `node:path`; no outbound markers.
+ *
+ * Restart semantics
+ * -----------------
+ * OpenClaw reads `openclaw.json` at gateway startup, not dynamically.
+ * When `patchOpenClawConfig` writes new keys during the CURRENT gateway
+ * boot, the keys take effect ONLY after the gateway is restarted. The
+ * plugin must tell the user via `api.logger.warn` so they know to run
+ * `/totalreclaw-restart` or restart the gateway manually.
+ *
+ * @param configPath  Absolute path to `openclaw.json`.
+ *                    Defaults to `<home>/.openclaw/openclaw.json`.
+ */
+export function patchOpenClawConfig(
+  configPath?: string,
+): OpenClawConfigPatchResult {
+  const home = process.env.HOME ?? '/home/node';
+  const target = configPath ?? path.join(home, '.openclaw', 'openclaw.json');
+
+  // `'skipped'` when the config file is absent — this host may not be
+  // running OpenClaw, or may use a non-standard config location.
+  if (!fs.existsSync(target)) return 'skipped';
+
+  try {
+    const raw = fs.readFileSync(target, 'utf-8');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cfg = JSON.parse(raw) as Record<string, any>;
+
+    // Ensure the `plugins` key exists.
+    if (typeof cfg.plugins !== 'object' || cfg.plugins === null) {
+      cfg.plugins = {};
+    }
+
+    let mutated = false;
+
+    // --- Fix #1: plugins.slots.memory = "totalreclaw" ---
+    if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
+      cfg.plugins.slots = {};
+    }
+    if (cfg.plugins.slots.memory !== 'totalreclaw') {
+      cfg.plugins.slots.memory = 'totalreclaw';
+      mutated = true;
+    }
+
+    // --- Fix #2: plugins.entries.totalreclaw.hooks.allowConversationAccess = true ---
+    if (typeof cfg.plugins.entries !== 'object' || cfg.plugins.entries === null) {
+      cfg.plugins.entries = {};
+    }
+    if (typeof cfg.plugins.entries.totalreclaw !== 'object' || cfg.plugins.entries.totalreclaw === null) {
+      cfg.plugins.entries.totalreclaw = {};
+    }
+    if (typeof cfg.plugins.entries.totalreclaw.hooks !== 'object' || cfg.plugins.entries.totalreclaw.hooks === null) {
+      cfg.plugins.entries.totalreclaw.hooks = {};
+    }
+    if (cfg.plugins.entries.totalreclaw.hooks.allowConversationAccess !== true) {
+      cfg.plugins.entries.totalreclaw.hooks.allowConversationAccess = true;
+      mutated = true;
+    }
+
+    if (!mutated) return 'unchanged';
+
+    // Write back with 2-space indent to match OpenClaw's own write style.
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n');
+    return 'patched';
+  } catch {
+    return 'error';
+  }
+}

package/index.ts

@@ -165,6 +165,7 @@ import {
   cleanupInstallStagingDirs,
   detectPartialInstall,
   clearPartialInstallMarker,
+  patchOpenClawConfig,
   writePluginManifest,
   writePluginError,
   readPluginLoadedManifest,
@@ -3108,6 +3109,48 @@ const plugin = {
       } catch {
         // Best-effort. Helper logs internally and never throws.
       }
+
+      // 3.3.9-rc.2 (issues #225 + #226): auto-patch openclaw.json for
+      // OpenClaw 2026.5.x. Two required config keys were not auto-applied
+      // by `openclaw plugins install` in 2026.5.x:
+      //
+      //   1. plugins.slots.memory = "totalreclaw"
+      //      OpenClaw 2026.5.x introduced memory-slot exclusivity — a
+      //      memory-kind plugin MUST explicitly claim the slot or it is
+      //      silently disabled (no error shown; `openclaw plugins inspect`
+      //      shows "memory slot set to memory-core"). #225.
+      //
+      //   2. plugins.entries.totalreclaw.hooks.allowConversationAccess = true
+      //      Non-bundled plugins in 2026.5.x require this flag to receive
+      //      agent_end and before_agent_start hooks. Without it, auto-
+      //      extraction and recall injection are silently disabled. #226.
+      //
+      // The patch is idempotent — if both keys are already correct the
+      // file is not touched. When the file IS mutated a restart is
+      // required for the new keys to take effect (OpenClaw reads
+      // openclaw.json at startup, not dynamically). We emit a warn so
+      // the user and ops scripts know to trigger a restart.
+      try {
+        const patchResult = patchOpenClawConfig();
+        if (patchResult === 'patched') {
+          api.logger.warn(
+            'TotalReclaw: updated openclaw.json with required 2026.5.x keys ' +
+              '(plugins.slots.memory + hooks.allowConversationAccess). ' +
+              'Gateway restart required for the changes to take effect. ' +
+              'Run `/totalreclaw-restart` or restart the gateway manually.',
+          );
+        } else if (patchResult === 'error') {
+          api.logger.warn(
+            'TotalReclaw: failed to auto-patch openclaw.json for OpenClaw 2026.5.x ' +
+              'compatibility. If memory hooks are silently disabled, add these keys ' +
+              'manually: plugins.slots.memory="totalreclaw" and ' +
+              'plugins.entries.totalreclaw.hooks.allowConversationAccess=true.',
+          );
+        }
+        // 'unchanged' and 'skipped' are silent — no log needed.
+      } catch {
+        // Best-effort — never let config-patch failure block plugin load.
+      }
     } catch {
       rcMode = false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.9-rc.1",
+  "version": "3.3.9-rc.2",
   "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": [

package/skill.json

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