@totalreclaw/totalreclaw 3.3.7-rc.2 → 3.3.8-rc.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.7-rc.3] — 2026-05-04
+
+Root cause of tool-binding gap on OpenClaw 2026.5.2: the plugin manifest (`openclaw.plugin.json`) was missing the `contracts.tools` declaration that OpenClaw 2026.5.2 now requires before any non-bundled plugin may register agent tools. Without it, every `api.registerTool()` call is silently rejected — `openclaw plugins doctor` shows 17× "plugin must declare contracts.tools before registering agent tools". The gateway loads the plugin module (ESM import succeeds, `plugins.allow` check passes) but no tools bind to any session, so `totalreclaw_pair` / `totalreclaw_remember` / etc. are invisible to the agent and auto-QA step 1 fails.
+
+The `plugins.allow` warning ("plugins.allow is empty; discovered non-bundled plugins may auto-load: totalreclaw") is a separate UX issue logged by the discoveryLoader when `plugins.allow` is absent — it is informational and does NOT prevent loading; the actual block is `contracts.tools`. Setting `plugins.allow=["totalreclaw"]` via `openclaw config set` is still recommended to suppress the noisy warning for users who follow the install guide, but it is not the root fix. See NOTE below.
+
+### Fixed — add `contracts.tools` to plugin manifest (issue #87 / FR #72097 tool-binding race)
+
+**Root cause:** OpenClaw 2026.5.2 (image `openclaw-qa:2026.5.2`) enforced a new security gate: non-bundled plugins must declare `contracts.tools` — an explicit allowlist of tool names — in their `openclaw.plugin.json` before registering any agent tool. Plugins that omit the field have every `registerTool` call silently dropped. The gate did not exist in ≤2026.4.24 (the version the plugin was built against), so the gap only surfaced when the QA container was upgraded.
+
+**Fix:** added `contracts.tools` to `skill/plugin/openclaw.plugin.json` listing all 17 tool names the plugin registers:
+`totalreclaw_remember`, `totalreclaw_recall`, `totalreclaw_forget`, `totalreclaw_export`, `totalreclaw_status`, `totalreclaw_preload_embedder`, `totalreclaw_consolidate`, `totalreclaw_pin`, `totalreclaw_unpin`, `totalreclaw_retype`, `totalreclaw_set_scope`, `totalreclaw_import_from`, `totalreclaw_import_batch`, `totalreclaw_upgrade`, `totalreclaw_migrate`, `totalreclaw_pair`, `totalreclaw_report_qa_bug`.
+
+**NOTE — `plugins.allow` side-effect:** OpenClaw 2026.5.2 also emits `plugins.allow is empty; discovered non-bundled plugins may auto-load: totalreclaw` as an INFO log whenever a session starts and `plugins.allow` is unset. The plugin install step (`openclaw plugins install @totalreclaw/totalreclaw@<ver>`) does NOT automatically add the plugin to `plugins.allow`. As a consequence, users who follow the public install guide hit this noisy warning every session. The `contracts.tools` fix resolves tool binding; the `plugins.allow` warning requires either (a) an upstream OpenClaw change to auto-populate `plugins.allow` on `plugins install`, or (b) adding `openclaw config set plugins.allow '["totalreclaw"]'` to the install guide as a one-time post-install step. Tracked as FR upstream; the setup guide has been updated to include the config set step.
+
 ## [3.3.7-rc.2] — 2026-05-04
 
 Follow-up to 3.3.7-rc.1, caught in Pedro's manual integration testing on the OpenClaw side 2026-05-03. The 5-tier auth fix shipped DEAD-CODE in rc.1: gateway logs surfaced `[gateway] [plugins] command registration failed: Command name "restart" is reserved by a built-in command (plugin=totalreclaw, source=/home/pdiogo/.openclaw/extensions/totalreclaw/dist/index.js)`. The plugin's `/restart` registration was rejected because OpenClaw's plugin registry hard-rejects `restart` (and the rest of `RESERVED_COMMANDS` — see `node_modules/openclaw/dist/registry-*.js` — `help`, `commands`, `status`, `whoami`, `context`, `stop`, `restart`, `reset`, `new`, `compact`, `config`, `debug`, `allowlist`, `activation`, `skill`, `subagents`, `kill`, `steer`, `tell`, `model`, `models`, `queue`, `send`, `bash`, `exec`, `think`, `verbose`, `reasoning`, `elevated`, `usage`). Built-in `/restart` retains its allow-from-only semantics, which is what gave Pedro the original "You are not authorized" — and our 5-tier fallback never ran because plugin registration never succeeded.

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.7-rc.2
+version: 3.3.8-rc.1
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -119,9 +119,48 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 - "status" → `totalreclaw_status`. "upgrade" → `totalreclaw_upgrade` (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
 - "import / export / consolidate" → `totalreclaw_import_from` (`dry_run=true` first; `_import_batch` for >50 chunks) · `totalreclaw_export` · `totalreclaw_consolidate` (`dry_run` first).
 
+## OpenClaw 2026.5.2 hybrid mode (issue #223 workaround — plugin 3.3.8-rc.1+)
+
+OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. Plugin 3.3.8-rc.1 ships a hybrid workaround:
+
+- **Hooks still fire**: `before_agent_start`, `agent_end`, `message_received`, `before_reset` use a separate code path not affected by issue #223. Auto-extraction, digest injection, preloading, and billing checks all work normally.
+- **Tools replaced by `tr` CLI**: instead of `totalreclaw_remember`, `totalreclaw_recall`, etc., use the `tr` binary installed with the plugin. The agent runs it via shell tool.
+
+**Agent usage under hybrid mode** (check `tr status` output for `hybrid-mode: yes`):
+
+```
+# remember a fact
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember "I work at Graph Foundation"
+# → outputs {"ok":true,"id":"...","text":"..."}
+
+# recall facts
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall "where does the user work"
+# → outputs {"ok":true,"count":1,"query":"...","memories":[...]}
+
+# status check
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status
+```
+
+Note: the `tr` bin name conflicts with the system `tr` utility; always invoke via full path `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd>` or the gateway host's equivalent path.
+
+**Required post-install config** (add to `~/.openclaw/openclaw.json`):
+```json
+{
+  "plugins": {
+    "entries": {
+      "totalreclaw": {
+        "hooks": { "allowConversationAccess": true }
+      }
+    }
+  }
+}
+```
+
+This unlocks typed hooks (`agent_end`, etc.) for non-bundled plugins. Without it, auto-extraction still works (extraction runs in `message_received`) but the `agent_end` hook that writes the digest is silently blocked.
+
 ## Diagnostics
 
-- `totalreclaw_*` tools not visible → plugin not installed or auto-reload didn't fire. Verify via `openclaw plugins list | grep totalreclaw` (or, on a managed service that doesn't expose the CLI, ask the user to confirm via their service's plugins UI). If `totalreclaw` is listed but tools are still absent, the gateway probably hasn't completed its auto-restart yet (give it 5-10s) OR `gateway.reload.mode = off` is set — instruct manual restart as fallback: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host), or the managed service's restart control. If the plugin is listed and the gateway has been restarted but tools are still missing (container-agent gap, issue #87), shell out to `openclaw totalreclaw pair generate --url-pin-only` on the gateway host and hand the user the `url` + `pin` from the JSON payload — OR `openclaw totalreclaw onboard --pair-only` (same flow, returns `pair_url` instead of `url`, issue #95). If your shell doesn't reach the gateway host (managed service), tell the user to install/enable the plugin via their service's plugins UI and restart the gateway via the service's restart control. Do NOT suggest the bare `openclaw totalreclaw onboard` (leaks phrase on stdout — deprecated in rc.18, removed next RC).
+- `totalreclaw_*` tools not visible → plugin not installed or auto-reload didn't fire. Verify via `openclaw plugins list | grep totalreclaw` (or, on a managed service that doesn't expose the CLI, ask the user to confirm via their service's plugins UI). If `totalreclaw` is listed but tools are still absent, the gateway probably hasn't completed its auto-restart yet (give it 5-10s) OR `gateway.reload.mode = off` is set — instruct manual restart as fallback: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host), or the managed service's restart control. If the plugin is listed and the gateway has been restarted but tools are still missing (container-agent gap, issue #87 / OC 2026.5.2 issue #223), switch to hybrid mode: use `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd>` for remember/recall/pair/status. If your shell doesn't reach the gateway host (managed service), tell the user to install/enable the plugin via their service's plugins UI and restart the gateway via the service's restart control. Do NOT suggest the bare `openclaw totalreclaw onboard` (leaks phrase on stdout — deprecated in rc.18, removed next RC).
 - User says done but `credentials.json` missing → PIN expired or entered wrong phrase; call `totalreclaw_pair` again.
 - `onboarding required` → credentials missing; redo from the account-setup step.
 - `quota exceeded` → `totalreclaw_status`, then offer `totalreclaw_upgrade`.

package/dist/index.js

@@ -2358,6 +2358,29 @@ const plugin = {
         // write would race that freeze.
         const _registeredToolNames = [];
         const _originalRegisterTool = api.registerTool.bind(api);
+        // 3.3.8-rc.1 HYBRID MODE (OpenClaw 2026.5.2 issue #223 workaround):
+        // The tool-policy-pipeline in OC 2026.5.2 strips non-bundled plugin tools
+        // before they reach the agent's session toolset. registerTool() calls
+        // succeed and tools are declared in contracts.tools, so the PLUGIN LOADS.
+        // But tool calls never reach execute() — the pipeline discards them before
+        // the agent's toolset is built.
+        //
+        // Strategy: keep all registerTool() calls intact so the plugin loader can
+        // verify the contracts.tools declaration and load the plugin (hooks fire).
+        // The `tr` CLI binary (dist/tr-cli.js) provides the alternative execution
+        // path. Agent runs `tr remember|recall|status|pair` from shell; tool calls
+        // are dead-letter but hooks (before_agent_start, agent_end, message_received,
+        // before_reset) still fire via the unbroken hook code path.
+        //
+        // NOTE: do NOT no-op registerTool here — OC 2026.5.2 validates the
+        // contracts.tools declaration against registered tools at load time and
+        // drops the plugin (unloads it) if no tools match. Confirmed empirically:
+        // no-op'ing registerTool causes the gateway to log "4 plugins" instead of
+        // "5 plugins" after restart (plugin excluded from active set).
+        //
+        // TODO: when OC ships a fix for issue #223, restore tool-call routing
+        // and remove the tr-cli.ts CLI layer. The bin/tr field in package.json
+        // can stay as a convenience CLI regardless.
         api.registerTool = (tool, opts) => {
             try {
                 const t = tool;
@@ -5932,9 +5955,14 @@ const plugin = {
                         loadedAt: Date.now(),
                         tools: _registeredToolNames.slice(),
                         version: pluginVersion ?? 'unknown',
+                        // 3.3.8-rc.1 hybrid mode annotation: tools ARE registered with the
+                        // SDK (required for plugin loader validation), but tool calls are
+                        // dead-letter on OC 2026.5.2 due to issue #223. Use `tr <cmd>` CLI.
+                        hybridMode: true,
+                        hybridCliTools: ['tr status', 'tr pair', 'tr remember', 'tr recall'],
                     });
                     if (ok) {
-                        api.logger.info(`TotalReclaw: wrote .loaded.json manifest (${_registeredToolNames.length} tools, version=${pluginVersion ?? 'unknown'})`);
+                        api.logger.info(`TotalReclaw: wrote .loaded.json manifest (${_registeredToolNames.length} tools + hybridCli=tr, version=${pluginVersion ?? 'unknown'})`);
                     }
                 }
                 catch {

package/dist/tr-cli.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * tr — TotalReclaw hybrid CLI (3.3.8-rc.1 workaround for OpenClaw 2026.5.2 issue #223)
+ *
+ * OpenClaw 2026.5.2 has a tool-policy-pipeline bug that strips non-bundled plugin tools
+ * before they reach the agent toolset. This CLI bypasses the broken tool-registration
+ * path entirely. The agent runs `tr <cmd>` from shell; the plugin keeps its hooks
+ * (before_agent_start, agent_end, message_received) via the unbroken hook code path.
+ *
+ * Phrase-safety: this CLI reads credentials.json (mnemonic at rest) but NEVER
+ * prints the mnemonic to stdout, stderr, or any log. Phrase only enters via QR-pair
+ * browser tier (pair-cli.ts / pair-cli-relay.ts — unchanged).
+ *
+ * Commands:
+ *   tr status               — print onboarding + credentials state
+ *   tr pair [--json]        — start a relay pairing session, print URL+PIN+QR
+ *   tr remember <text>      — store a memory in the encrypted vault
+ *   tr recall <query>       — search the encrypted vault, print results as JSON
+ *
+ * Install: wired via package.json `bin.tr` → dist/tr-cli.js
+ * Usage from container: `docker exec tr-openclaw tr status`
+ */
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { CONFIG } from './config.js';
+import { loadCredentialsJson } from './fs-helpers.js';
+import { printStatus } from './onboarding-cli.js';
+import { deriveKeys, computeAuthKeyHash, encrypt, decrypt, generateBlindIndices, generateContentFingerprint, } from './crypto.js';
+import { createApiClient } from './api-client.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const CREDENTIALS_PATH = CONFIG.credentialsPath;
+const SERVER_URL = CONFIG.serverUrl;
+const STATE_PATH = CONFIG.onboardingStatePath;
+function die(msg, code = 1) {
+    process.stderr.write(`tr: ${msg}\n`);
+    process.exit(code);
+}
+function log(msg) {
+    process.stdout.write(msg + '\n');
+}
+async function buildContext() {
+    const creds = loadCredentialsJson(CREDENTIALS_PATH);
+    if (!creds) {
+        die('TotalReclaw is not set up. Run: openclaw totalreclaw onboard\n(or: tr pair)');
+    }
+    const mnemonic = (typeof creds.mnemonic === 'string' && creds.mnemonic.trim()) ||
+        (typeof creds.recovery_phrase === 'string' && creds.recovery_phrase.trim()) ||
+        '';
+    if (!mnemonic) {
+        die('No recovery phrase in credentials.json. Run: openclaw totalreclaw onboard');
+    }
+    // Parse existing salt/userId from credentials.json
+    let existingSalt;
+    let existingUserId;
+    const saltStr = typeof creds.salt === 'string' ? creds.salt : undefined;
+    if (saltStr) {
+        if (/^[0-9a-f]{64}$/i.test(saltStr)) {
+            existingSalt = Buffer.from(saltStr, 'hex');
+        }
+        else {
+            existingSalt = Buffer.from(saltStr, 'base64');
+        }
+    }
+    existingUserId = typeof creds.userId === 'string' ? creds.userId : undefined;
+    const keys = deriveKeys(mnemonic, existingSalt);
+    const authKeyHex = keys.authKey.toString('hex');
+    const apiClient = createApiClient(SERVER_URL);
+    let userId;
+    if (existingUserId) {
+        userId = existingUserId;
+    }
+    else {
+        // Register to get userId (idempotent on relay)
+        const authHash = computeAuthKeyHash(keys.authKey);
+        const saltHex = keys.salt.toString('hex');
+        try {
+            const result = await apiClient.register(authHash, saltHex);
+            userId = result.user_id;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('USER_EXISTS')) {
+                userId = authHash.slice(0, 32);
+            }
+            else {
+                die(`Relay registration failed: ${msg}`);
+            }
+        }
+    }
+    return {
+        authKeyHex,
+        encryptionKey: keys.encryptionKey,
+        dedupKey: keys.dedupKey,
+        apiClient,
+        userId,
+    };
+}
+// ---------------------------------------------------------------------------
+// Command: status
+// ---------------------------------------------------------------------------
+async function cmdStatus() {
+    // Print onboarding + credentials state (never prints mnemonic — same as
+    // the `openclaw totalreclaw status` subcommand surface).
+    printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
+    // Additional: loaded.json check to confirm plugin hooks are active.
+    // Reads manifest written by register() in index.ts.
+    // Probe both install paths: extensions/ (local tgz installs) and npm/ (registry installs).
+    try {
+        const fs = await import('node:fs');
+        const candidatePaths = [
+            // extensions-path (local tgz / --force install) — .loaded.json sits at root, not dist/
+            path.join(os.homedir(), '.openclaw', 'extensions', 'totalreclaw', '.loaded.json'),
+            // npm-path (registry install) — .loaded.json inside dist/
+            path.join(os.homedir(), '.openclaw', 'npm', 'node_modules', '@totalreclaw', 'totalreclaw', 'dist', '.loaded.json'),
+        ];
+        const resolvedPath = candidatePaths.find((p) => fs.existsSync(p));
+        if (resolvedPath) {
+            const raw = fs.readFileSync(resolvedPath, 'utf-8');
+            const manifest = JSON.parse(raw);
+            const ageMs = Date.now() - (manifest.loadedAt ?? 0);
+            const ageSec = Math.round(ageMs / 1000);
+            process.stdout.write(`\n  plugin:      loaded (version=${manifest.version ?? '?'} bootCount=${manifest.bootCount ?? '?'} loaded=${ageSec}s ago)\n` +
+                `  hybrid-mode: ${manifest.hybridMode ? 'yes (use tr <cmd>)' : 'no'}\n` +
+                `  hooks:       before_agent_start, agent_end, message_received, before_reset\n` +
+                `  note:        tools from .loaded.json are STRIPPED by OC 2026.5.2 issue #223;\n` +
+                `               use \`tr <cmd>\` from shell instead\n`);
+        }
+        else {
+            process.stdout.write('\n  plugin:      .loaded.json not found — plugin may not be loaded\n');
+        }
+    }
+    catch {
+        // Best-effort
+    }
+}
+// ---------------------------------------------------------------------------
+// Command: pair
+// ---------------------------------------------------------------------------
+async function cmdPair(args) {
+    // Delegate to the existing pair-cli-relay.ts via a thin wrapper.
+    // The pair flow is relay-brokered (works through Docker NAT).
+    // Phrase-safety: pair-cli-relay.ts is x25519-only; mnemonic never appears.
+    const outputMode = args.includes('--json') ? 'json' : args.includes('--url-pin') ? 'url-pin' : 'human';
+    const { runRelayPairCli } = await import('./pair-cli-relay.js');
+    const { defaultRenderQr, buildDefaultPairCliIo } = await import('./pair-cli.js');
+    const io = buildDefaultPairCliIo();
+    const outcome = await runRelayPairCli('generate', {
+        relayBaseUrl: CONFIG.pairRelayUrl,
+        credentialsPath: CREDENTIALS_PATH,
+        onboardingStatePath: STATE_PATH,
+        logger: {
+            info: (m) => process.stderr.write(`[info] ${m}\n`),
+            warn: (m) => process.stderr.write(`[warn] ${m}\n`),
+            error: (m) => process.stderr.write(`[error] ${m}\n`),
+        },
+        pluginVersion: '3.3.8-rc.1',
+        deriveScopeAddress: undefined,
+        renderQr: defaultRenderQr,
+        io,
+        outputMode: outputMode,
+    });
+    if (outcome.status !== 'completed' && outcome.status !== 'canceled') {
+        die(`Pairing ${outcome.status}`, 1);
+    }
+    if (outcome.status === 'canceled') {
+        process.exit(130);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command: remember
+// ---------------------------------------------------------------------------
+async function cmdRemember(args) {
+    const text = args.join(' ').trim();
+    if (!text) {
+        die('Usage: tr remember <text>');
+    }
+    const ctx = await buildContext();
+    // Build a minimal MemoryTaxonomy v1 claim blob (same format as storeExtractedFacts)
+    const now = new Date().toISOString();
+    const factId = randomUUID().replace(/-/g, '');
+    // Encrypt the memory text
+    const blob = JSON.stringify({
+        text,
+        type: 'claim',
+        source: 'user',
+        scope: 'unspecified',
+        importance: 8,
+        metadata: {
+            type: 'claim',
+            source: 'user',
+            scope: 'unspecified',
+            importance: 8,
+        },
+        timestamp: now,
+        version: 'v1',
+    });
+    const encrypted_blob = encrypt(blob, ctx.encryptionKey);
+    const blind_indices = generateBlindIndices(text);
+    const content_fp = generateContentFingerprint(text, ctx.dedupKey);
+    const payload = {
+        id: factId,
+        timestamp: now,
+        encrypted_blob,
+        blind_indices,
+        decay_score: 8,
+        source: 'cli:tr-remember',
+        content_fp,
+    };
+    try {
+        await ctx.apiClient.store(ctx.userId, [payload], ctx.authKeyHex);
+        log(JSON.stringify({ ok: true, id: factId, text }));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        die(`remember failed: ${msg}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command: recall
+// ---------------------------------------------------------------------------
+async function cmdRecall(args) {
+    const query = args.join(' ').trim();
+    if (!query) {
+        die('Usage: tr recall <query>');
+    }
+    const ctx = await buildContext();
+    // Generate word trapdoors for blind search
+    const trapdoors = generateBlindIndices(query);
+    if (trapdoors.length === 0) {
+        log(JSON.stringify({ ok: true, count: 0, memories: [] }));
+        return;
+    }
+    try {
+        const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, 12, ctx.authKeyHex);
+        const memories = [];
+        for (const c of candidates) {
+            try {
+                const raw = decrypt(c.encrypted_blob, ctx.encryptionKey);
+                const parsed = JSON.parse(raw);
+                if (parsed.text) {
+                    memories.push({
+                        id: c.fact_id,
+                        text: parsed.text,
+                        score: c.decay_score,
+                        timestamp: new Date(c.timestamp).toISOString(),
+                    });
+                }
+            }
+            catch {
+                // Skip undecryptable
+            }
+        }
+        // Simple relevance sort by decay_score (descending)
+        memories.sort((a, b) => b.score - a.score);
+        log(JSON.stringify({ ok: true, count: memories.length, query, memories }));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        die(`recall failed: ${msg}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    switch (cmd) {
+        case 'status':
+            await cmdStatus();
+            break;
+        case 'pair':
+            await cmdPair(args.slice(1));
+            break;
+        case 'remember':
+            await cmdRemember(args.slice(1));
+            break;
+        case 'recall':
+            await cmdRecall(args.slice(1));
+            break;
+        case undefined:
+        case '--help':
+        case '-h':
+            process.stdout.write('TotalReclaw hybrid CLI (OpenClaw 2026.5.2 issue #223 workaround)\n\n' +
+                'Usage:\n' +
+                '  tr status              — onboarding + plugin load state\n' +
+                '  tr pair [--json]       — start a relay pairing session\n' +
+                '  tr remember <text>     — store a memory\n' +
+                '  tr recall <query>      — search memories (outputs JSON)\n\n' +
+                'Environment:\n' +
+                '  TOTALRECLAW_SERVER_URL — relay URL (default: api-staging.totalreclaw.xyz)\n' +
+                '  TOTALRECLAW_CREDENTIALS_PATH — override credentials.json path\n');
+            break;
+        default:
+            die(`Unknown command: ${cmd}. Run \`tr --help\` for usage.`);
+    }
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`tr: fatal: ${msg}\n`);
+    process.exit(2);
+});

package/fs-helpers.ts

@@ -594,6 +594,18 @@ export interface PluginLoadManifest {
    * verify the manifest is from the currently-running container vs a
    * stale-mounted copy. */
   pid?: number;
+  /**
+   * 3.3.8-rc.1 — true when registerTool() calls are no-op'd due to the
+   * OC 2026.5.2 issue #223 hybrid workaround. Tools in `tools[]` are
+   * exposed via the `tr` CLI binary instead of via the plugin API.
+   */
+  hybridMode?: boolean;
+  /**
+   * 3.3.8-rc.1 — CLI commands that replace the tool registrations
+   * when hybridMode=true. Agent runs these from shell instead of using
+   * tool calls.
+   */
+  hybridCliTools?: string[];
 }
 
 /** Schema written to `.error.json` when register() throws. */

package/index.ts

@@ -2926,6 +2926,29 @@ const plugin = {
     // write would race that freeze.
     const _registeredToolNames: string[] = [];
     const _originalRegisterTool = api.registerTool.bind(api);
+    // 3.3.8-rc.1 HYBRID MODE (OpenClaw 2026.5.2 issue #223 workaround):
+    // The tool-policy-pipeline in OC 2026.5.2 strips non-bundled plugin tools
+    // before they reach the agent's session toolset. registerTool() calls
+    // succeed and tools are declared in contracts.tools, so the PLUGIN LOADS.
+    // But tool calls never reach execute() — the pipeline discards them before
+    // the agent's toolset is built.
+    //
+    // Strategy: keep all registerTool() calls intact so the plugin loader can
+    // verify the contracts.tools declaration and load the plugin (hooks fire).
+    // The `tr` CLI binary (dist/tr-cli.js) provides the alternative execution
+    // path. Agent runs `tr remember|recall|status|pair` from shell; tool calls
+    // are dead-letter but hooks (before_agent_start, agent_end, message_received,
+    // before_reset) still fire via the unbroken hook code path.
+    //
+    // NOTE: do NOT no-op registerTool here — OC 2026.5.2 validates the
+    // contracts.tools declaration against registered tools at load time and
+    // drops the plugin (unloads it) if no tools match. Confirmed empirically:
+    // no-op'ing registerTool causes the gateway to log "4 plugins" instead of
+    // "5 plugins" after restart (plugin excluded from active set).
+    //
+    // TODO: when OC ships a fix for issue #223, restore tool-call routing
+    // and remove the tr-cli.ts CLI layer. The bin/tr field in package.json
+    // can stay as a convenience CLI regardless.
     api.registerTool = (tool: unknown, opts?: { name?: string; names?: string[] }) => {
       try {
         const t = tool as { name?: unknown } | null | undefined;
@@ -6917,10 +6940,15 @@ const plugin = {
           loadedAt: Date.now(),
           tools: _registeredToolNames.slice(),
           version: pluginVersion ?? 'unknown',
+          // 3.3.8-rc.1 hybrid mode annotation: tools ARE registered with the
+          // SDK (required for plugin loader validation), but tool calls are
+          // dead-letter on OC 2026.5.2 due to issue #223. Use `tr <cmd>` CLI.
+          hybridMode: true,
+          hybridCliTools: ['tr status', 'tr pair', 'tr remember', 'tr recall'],
         });
         if (ok) {
           api.logger.info(
-            `TotalReclaw: wrote .loaded.json manifest (${_registeredToolNames.length} tools, version=${pluginVersion ?? 'unknown'})`,
+            `TotalReclaw: wrote .loaded.json manifest (${_registeredToolNames.length} tools + hybridCli=tr, version=${pluginVersion ?? 'unknown'})`,
           );
         }
       } catch {

package/openclaw.plugin.json

@@ -2,6 +2,28 @@
   "id": "totalreclaw",
   "name": "TotalReclaw",
   "description": "End-to-end encrypted memory vault for AI agents",
+  "kind": "memory",
+  "contracts": {
+    "tools": [
+      "totalreclaw_remember",
+      "totalreclaw_recall",
+      "totalreclaw_forget",
+      "totalreclaw_export",
+      "totalreclaw_status",
+      "totalreclaw_preload_embedder",
+      "totalreclaw_consolidate",
+      "totalreclaw_pin",
+      "totalreclaw_unpin",
+      "totalreclaw_retype",
+      "totalreclaw_set_scope",
+      "totalreclaw_import_from",
+      "totalreclaw_import_batch",
+      "totalreclaw_upgrade",
+      "totalreclaw_migrate",
+      "totalreclaw_pair",
+      "totalreclaw_report_qa_bug"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.7-rc.2",
+  "version": "3.3.8-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": [
@@ -48,6 +48,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "tr": "./dist/tr-cli.js"
+  },
   "files": [
     "dist/",
     "*.ts",

package/skill.json

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

package/tr-cli.ts

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * tr — TotalReclaw hybrid CLI (3.3.8-rc.1 workaround for OpenClaw 2026.5.2 issue #223)
+ *
+ * OpenClaw 2026.5.2 has a tool-policy-pipeline bug that strips non-bundled plugin tools
+ * before they reach the agent toolset. This CLI bypasses the broken tool-registration
+ * path entirely. The agent runs `tr <cmd>` from shell; the plugin keeps its hooks
+ * (before_agent_start, agent_end, message_received) via the unbroken hook code path.
+ *
+ * Phrase-safety: this CLI reads credentials.json (mnemonic at rest) but NEVER
+ * prints the mnemonic to stdout, stderr, or any log. Phrase only enters via QR-pair
+ * browser tier (pair-cli.ts / pair-cli-relay.ts — unchanged).
+ *
+ * Commands:
+ *   tr status               — print onboarding + credentials state
+ *   tr pair [--json]        — start a relay pairing session, print URL+PIN+QR
+ *   tr remember <text>      — store a memory in the encrypted vault
+ *   tr recall <query>       — search the encrypted vault, print results as JSON
+ *
+ * Install: wired via package.json `bin.tr` → dist/tr-cli.js
+ * Usage from container: `docker exec tr-openclaw tr status`
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+import { CONFIG } from './config.js';
+import { loadCredentialsJson } from './fs-helpers.js';
+import { printStatus } from './onboarding-cli.js';
+import {
+  deriveKeys,
+  computeAuthKeyHash,
+  encrypt,
+  decrypt,
+  generateBlindIndices,
+  generateContentFingerprint,
+} from './crypto.js';
+import { createApiClient } from './api-client.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const CREDENTIALS_PATH = CONFIG.credentialsPath;
+const SERVER_URL = CONFIG.serverUrl;
+const STATE_PATH = CONFIG.onboardingStatePath;
+
+function die(msg: string, code = 1): never {
+  process.stderr.write(`tr: ${msg}\n`);
+  process.exit(code);
+}
+
+function log(msg: string): void {
+  process.stdout.write(msg + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Core init — minimal version of index.ts initialize()
+// ---------------------------------------------------------------------------
+
+interface CliContext {
+  authKeyHex: string;
+  encryptionKey: Buffer;
+  dedupKey: Buffer;
+  apiClient: ReturnType<typeof createApiClient>;
+  userId: string;
+}
+
+async function buildContext(): Promise<CliContext> {
+  const creds = loadCredentialsJson(CREDENTIALS_PATH);
+  if (!creds) {
+    die('TotalReclaw is not set up. Run: openclaw totalreclaw onboard\n(or: tr pair)');
+  }
+
+  const mnemonic =
+    (typeof creds.mnemonic === 'string' && creds.mnemonic.trim()) ||
+    (typeof creds.recovery_phrase === 'string' && creds.recovery_phrase.trim()) ||
+    '';
+
+  if (!mnemonic) {
+    die('No recovery phrase in credentials.json. Run: openclaw totalreclaw onboard');
+  }
+
+  // Parse existing salt/userId from credentials.json
+  let existingSalt: Buffer | undefined;
+  let existingUserId: string | undefined;
+
+  const saltStr = typeof creds.salt === 'string' ? creds.salt : undefined;
+  if (saltStr) {
+    if (/^[0-9a-f]{64}$/i.test(saltStr)) {
+      existingSalt = Buffer.from(saltStr, 'hex');
+    } else {
+      existingSalt = Buffer.from(saltStr, 'base64');
+    }
+  }
+  existingUserId = typeof creds.userId === 'string' ? creds.userId : undefined;
+
+  const keys = deriveKeys(mnemonic, existingSalt);
+  const authKeyHex = keys.authKey.toString('hex');
+
+  const apiClient = createApiClient(SERVER_URL);
+
+  let userId: string;
+  if (existingUserId) {
+    userId = existingUserId;
+  } else {
+    // Register to get userId (idempotent on relay)
+    const authHash = computeAuthKeyHash(keys.authKey);
+    const saltHex = keys.salt.toString('hex');
+    try {
+      const result = await apiClient.register(authHash, saltHex);
+      userId = result.user_id;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('USER_EXISTS')) {
+        userId = authHash.slice(0, 32);
+      } else {
+        die(`Relay registration failed: ${msg}`);
+      }
+    }
+  }
+
+  return {
+    authKeyHex,
+    encryptionKey: keys.encryptionKey,
+    dedupKey: keys.dedupKey,
+    apiClient,
+    userId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Command: status
+// ---------------------------------------------------------------------------
+
+async function cmdStatus(): Promise<void> {
+  // Print onboarding + credentials state (never prints mnemonic — same as
+  // the `openclaw totalreclaw status` subcommand surface).
+  printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
+
+  // Additional: loaded.json check to confirm plugin hooks are active.
+  // Reads manifest written by register() in index.ts.
+  // Probe both install paths: extensions/ (local tgz installs) and npm/ (registry installs).
+  try {
+    const fs = await import('node:fs');
+    const candidatePaths = [
+      // extensions-path (local tgz / --force install) — .loaded.json sits at root, not dist/
+      path.join(os.homedir(), '.openclaw', 'extensions', 'totalreclaw', '.loaded.json'),
+      // npm-path (registry install) — .loaded.json inside dist/
+      path.join(os.homedir(), '.openclaw', 'npm', 'node_modules', '@totalreclaw', 'totalreclaw', 'dist', '.loaded.json'),
+    ];
+    const resolvedPath = candidatePaths.find((p) => fs.existsSync(p));
+    if (resolvedPath) {
+      const raw = fs.readFileSync(resolvedPath, 'utf-8');
+      const manifest = JSON.parse(raw) as {
+        version?: string;
+        bootCount?: number;
+        loadedAt?: number;
+        hybridMode?: boolean;
+        tools?: string[];
+      };
+      const ageMs = Date.now() - (manifest.loadedAt ?? 0);
+      const ageSec = Math.round(ageMs / 1000);
+      process.stdout.write(
+        `\n  plugin:      loaded (version=${manifest.version ?? '?'} bootCount=${manifest.bootCount ?? '?'} loaded=${ageSec}s ago)\n` +
+        `  hybrid-mode: ${manifest.hybridMode ? 'yes (use tr <cmd>)' : 'no'}\n` +
+        `  hooks:       before_agent_start, agent_end, message_received, before_reset\n` +
+        `  note:        tools from .loaded.json are STRIPPED by OC 2026.5.2 issue #223;\n` +
+        `               use \`tr <cmd>\` from shell instead\n`,
+      );
+    } else {
+      process.stdout.write('\n  plugin:      .loaded.json not found — plugin may not be loaded\n');
+    }
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command: pair
+// ---------------------------------------------------------------------------
+
+async function cmdPair(args: string[]): Promise<void> {
+  // Delegate to the existing pair-cli-relay.ts via a thin wrapper.
+  // The pair flow is relay-brokered (works through Docker NAT).
+  // Phrase-safety: pair-cli-relay.ts is x25519-only; mnemonic never appears.
+  const outputMode = args.includes('--json') ? 'json' : args.includes('--url-pin') ? 'url-pin' : 'human';
+
+  const { runRelayPairCli } = await import('./pair-cli-relay.js');
+  const { defaultRenderQr, buildDefaultPairCliIo } = await import('./pair-cli.js');
+
+  const io = buildDefaultPairCliIo();
+  const outcome = await runRelayPairCli('generate', {
+    relayBaseUrl: CONFIG.pairRelayUrl,
+    credentialsPath: CREDENTIALS_PATH,
+    onboardingStatePath: STATE_PATH,
+    logger: {
+      info: (m: string) => process.stderr.write(`[info] ${m}\n`),
+      warn: (m: string) => process.stderr.write(`[warn] ${m}\n`),
+      error: (m: string) => process.stderr.write(`[error] ${m}\n`),
+    },
+    pluginVersion: '3.3.8-rc.1',
+    deriveScopeAddress: undefined,
+    renderQr: defaultRenderQr,
+    io,
+    outputMode: outputMode as import('./pair-cli.js').PairCliOutputMode,
+  });
+
+  if (outcome.status !== 'completed' && outcome.status !== 'canceled') {
+    die(`Pairing ${outcome.status}`, 1);
+  }
+  if (outcome.status === 'canceled') {
+    process.exit(130);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command: remember
+// ---------------------------------------------------------------------------
+
+async function cmdRemember(args: string[]): Promise<void> {
+  const text = args.join(' ').trim();
+  if (!text) {
+    die('Usage: tr remember <text>');
+  }
+
+  const ctx = await buildContext();
+
+  // Build a minimal MemoryTaxonomy v1 claim blob (same format as storeExtractedFacts)
+  const now = new Date().toISOString();
+  const factId = randomUUID().replace(/-/g, '');
+
+  // Encrypt the memory text
+  const blob = JSON.stringify({
+    text,
+    type: 'claim',
+    source: 'user',
+    scope: 'unspecified',
+    importance: 8,
+    metadata: {
+      type: 'claim',
+      source: 'user',
+      scope: 'unspecified',
+      importance: 8,
+    },
+    timestamp: now,
+    version: 'v1',
+  });
+  const encrypted_blob = encrypt(blob, ctx.encryptionKey);
+  const blind_indices = generateBlindIndices(text);
+  const content_fp = generateContentFingerprint(text, ctx.dedupKey);
+
+  const payload = {
+    id: factId,
+    timestamp: now,
+    encrypted_blob,
+    blind_indices,
+    decay_score: 8,
+    source: 'cli:tr-remember',
+    content_fp,
+  };
+
+  try {
+    await ctx.apiClient.store(ctx.userId, [payload], ctx.authKeyHex);
+    log(JSON.stringify({ ok: true, id: factId, text }));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    die(`remember failed: ${msg}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command: recall
+// ---------------------------------------------------------------------------
+
+async function cmdRecall(args: string[]): Promise<void> {
+  const query = args.join(' ').trim();
+  if (!query) {
+    die('Usage: tr recall <query>');
+  }
+
+  const ctx = await buildContext();
+
+  // Generate word trapdoors for blind search
+  const trapdoors = generateBlindIndices(query);
+
+  if (trapdoors.length === 0) {
+    log(JSON.stringify({ ok: true, count: 0, memories: [] }));
+    return;
+  }
+
+  try {
+    const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, 12, ctx.authKeyHex);
+
+    const memories: Array<{ id: string; text: string; score: number; timestamp: string }> = [];
+
+    for (const c of candidates) {
+      try {
+        const raw = decrypt(c.encrypted_blob, ctx.encryptionKey);
+        const parsed = JSON.parse(raw) as { text?: string };
+        if (parsed.text) {
+          memories.push({
+            id: c.fact_id,
+            text: parsed.text,
+            score: c.decay_score,
+            timestamp: new Date(c.timestamp).toISOString(),
+          });
+        }
+      } catch {
+        // Skip undecryptable
+      }
+    }
+
+    // Simple relevance sort by decay_score (descending)
+    memories.sort((a, b) => b.score - a.score);
+
+    log(JSON.stringify({ ok: true, count: memories.length, query, memories }));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    die(`recall failed: ${msg}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  switch (cmd) {
+    case 'status':
+      await cmdStatus();
+      break;
+
+    case 'pair':
+      await cmdPair(args.slice(1));
+      break;
+
+    case 'remember':
+      await cmdRemember(args.slice(1));
+      break;
+
+    case 'recall':
+      await cmdRecall(args.slice(1));
+      break;
+
+    case undefined:
+    case '--help':
+    case '-h':
+      process.stdout.write(
+        'TotalReclaw hybrid CLI (OpenClaw 2026.5.2 issue #223 workaround)\n\n' +
+        'Usage:\n' +
+        '  tr status              — onboarding + plugin load state\n' +
+        '  tr pair [--json]       — start a relay pairing session\n' +
+        '  tr remember <text>     — store a memory\n' +
+        '  tr recall <query>      — search memories (outputs JSON)\n\n' +
+        'Environment:\n' +
+        '  TOTALRECLAW_SERVER_URL — relay URL (default: api-staging.totalreclaw.xyz)\n' +
+        '  TOTALRECLAW_CREDENTIALS_PATH — override credentials.json path\n',
+      );
+      break;
+
+    default:
+      die(`Unknown command: ${cmd}. Run \`tr --help\` for usage.`);
+  }
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`tr: fatal: ${msg}\n`);
+  process.exit(2);
+});