@totalreclaw/totalreclaw 3.3.1-rc.7 → 3.3.1-rc.9

package/CHANGELOG.md

@@ -4,6 +4,208 @@ 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.1-rc.9] — 2026-04-23
+
+Coordinated version bump with Hermes Python `2.3.1rc9`. Plugin code itself is unchanged from `3.3.1-rc.6` (the first-run banner fix lives entirely on the Python side — `totalreclaw.onboarding.maybe_emit_welcome`). The rc.9 bundle ships the Hermes-side banner suppression and keeps plugin + Python versions aligned so the release-pipeline tracker can carry them through QA as one artifact set.
+
+### Why a plugin bump when only Python changed
+
+Our RC cadence publishes both registries from the same bundle. Out-of-sync version tags cause downstream confusion (the `qa-totalreclaw` skill and the release-pipeline tracker both key on a single RC-number per wave). Skipping the plugin bump would leave rc.9 documented on the Python side only; a later plugin bug would then have to skip to rc.10 to catch up. Much simpler to bump both in lockstep.
+
+See `python/CHANGELOG.md` (the `2.3.1rc9` entry) for the underlying fix: suppress the first-run welcome banner emitted by `totalreclaw.onboarding.maybe_emit_welcome`. Two problems surfaced during the rc.8 Hermes auto-QA run:
+
+1. **Chat-breaker.** The banner dominated `hermes chat -q` stdout when credentials were absent, breaking the QA harness's `session_id` parsing on every fresh install.
+2. **Phrase-safety violation.** The banner told users to `Run: totalreclaw setup` — a CLI that emits the recovery phrase to stdout. In an agent-driven context, stdout is echoed back into LLM context, so the phrase would cross the LLM boundary in violation of `project_phrase_safety_rule.md`.
+
+Agent-driven setup now routes through the `totalreclaw_pair` tool (browser-side crypto, phrase-safe) per SKILL.md. User-in-terminal setup still runs through `totalreclaw setup` / `openclaw totalreclaw onboard` OUTSIDE any agent context.
+
+### Skipped
+
+- **`3.3.1-rc.7`** and **`3.3.1-rc.8`** — registry-only bumps from 2026-04-22 workflow dispatches; the git repo on `main` carried rc.6 code unchanged through both publishes.
+
+## [3.3.1-rc.6] — 2026-04-22
+
+Coordinated version bump with Hermes Python `2.3.1rc6`. Plugin code itself is unchanged from `3.3.1-rc.4` (the OpenClaw plugin's `register()` path already wired every tool advertised in `skill.yaml`). The rc.6 bundle ships the Hermes-side tool-registration fix and keeps plugin + Python versions aligned so the release-pipeline tracker can carry them through QA as one artifact set.
+
+### Why a plugin bump when only Python changed
+
+Our RC cadence publishes both registries from the same bundle. Out-of-sync version tags cause downstream confusion (the `qa-totalreclaw` skill and the release-pipeline tracker both key on a single RC-number per wave). Skipping the plugin bump would leave rc.6 documented on the Python side only; a later plugin bug would then have to skip to rc.7 to catch up. Much simpler to bump both in lockstep.
+
+### Skipped
+
+- **`3.3.1-rc.5`** — PR #76 (branch `fix/plugin-3.3.1-rc.5-qr-display`) remained unmerged when the rc.4 Hermes regression was escalated. rc.5's QR-display work rebases onto rc.6 as a follow-up.
+
+## [3.3.1-rc.4] — 2026-04-22
+
+Phrase-safety hardening: `totalreclaw_onboard` agent tool removed. Paired with Hermes Python `2.3.1rc4` (which ports the QR-pair flow to Python so Hermes users gain a phrase-safe agent setup path too).
+
+### Removed (phrase-safety enforcement — BREAKING for agent tool callers)
+
+- **`totalreclaw_onboard` agent tool — REMOVED.** rc.3 shipped a `totalreclaw_onboard` tool that generated a fresh BIP-39 mnemonic in-process, wrote it to `credentials.json`, and returned `{scope_address, credentials_path}`. `emitPhrase: false` kept the mnemonic out of the tool's return payload, but NOTHING ARCHITECTURALLY PREVENTED leakage — a future patch could regress the flag, a different code path could echo the mnemonic in a log/error, or the mere existence of the tool signalled to agents that phrase generation inside chat is fine (it isn't). Per `project_phrase_safety_rule.md`: "recovery phrase MUST NEVER cross the LLM context in ANY form." rc.4 removes the registration. The underlying `runNonInteractiveOnboard` code path stays reachable via the CLI `openclaw totalreclaw onboard` — that path runs in the user's own terminal, OUTSIDE any agent shell, so phrase stdout never feeds back into LLM context.
+
+### Changed
+
+- **`SKILL.md` — setup section rewritten.** `totalreclaw_pair` is now the canonical setup surface for all users (local or remote). The CLI wizard (`openclaw totalreclaw onboard`) is explicitly documented as user-terminal-only — agents MUST NOT invoke it via their shell tool. Tool surface table updated: `totalreclaw_onboard` removed, `totalreclaw_pair` promoted to canonical. `totalreclaw_onboarding_start` remains as a pointer-only tool for users who explicitly prefer local-terminal setup.
+- **`index.ts` — `totalreclaw_pair` tool description updated.** Removed backref to `totalreclaw_onboard`; now instructs agents to always prefer pair, with `totalreclaw_onboarding_start` as the fallback pointer for local-terminal-only users.
+- **`docs/guides/openclaw-setup.md` — QR pairing is now documented as the default setup flow.** CLI wizard moved to a user-terminal-only subsection with a prominent "do NOT run this through an agent shell" warning.
+
+### Tests
+
+- **`phrase-safety-registry.test.ts`** — new. Text-scans `index.ts` for `api.registerTool({ name: '...' })` literals and asserts: (a) `totalreclaw_onboard` is NOT in the list; (b) `totalreclaw_pair` IS in the list; (c) no name contains phrase-adjacent tokens (`onboard_generate`, `generate_phrase`, `generate_mnemonic`, `restore_phrase`, `restore_mnemonic`, `mnemonic`). Runs as part of `npm test`.
+
+## [3.3.1-rc.3] — 2026-04-22
+
+Patch RC bundling two stability fixes, one new RC-gated tool, two SKILL.md addendums, and a configurable LLM retry budget. All prior rc.1 + rc.2 fixes are preserved.
+
+### Changed
+
+- **`llm-client.ts` — configurable `ZAI_BASE_URL` + auto-fallback on "Insufficient balance" 429.** rc.2 QA surfaced that GLM Coding Plan keys hitting the STANDARD zai endpoint (and PAYG keys hitting CODING) return HTTP 429 with body `"Insufficient balance or no resource package. Please recharge."` — misleading because the key itself is valid. rc.3: (a) accepts `ZAI_BASE_URL` env override via `config.ts` / `getZaiBaseUrl()`; (b) auto-detects the error signature and flips CODING ↔ STANDARD once per call (logged at INFO). SKILL.md now documents "GLM Coding Plan → leave unset; PAYG → set `ZAI_BASE_URL=https://api.z.ai/api/paas/v4`."
+- **`llm-client.ts` — retry budget 7s → ~62s (configurable).** rc.1/rc.2 QA: 5–9 of 10 extraction windows returned 0 facts against multi-minute upstream 429 storms. The 3-attempt 1s/2s/4s backoff couldn't outlast a 9-minute outage. rc.3: 5 attempts, 2s/4s/8s/16s/32s backoff, total ~62s. Configurable via `TOTALRECLAW_LLM_RETRY_BUDGET_MS` env (default 60_000). First retry logs at INFO, rest at DEBUG (debounced — no spam during long outages). On exhaustion throws `LLMUpstreamOutageError` (structured, `attempts` + `lastStatus`) so extraction callers can recognise vs bail silently. Non-retryable errors (401/403/404/parse) still propagate as plain `Error`.
+- **`subgraph-store.ts` — per-account submission mutex.** rc.2 logged 16 AA25 `invalid account nonce` events from concurrent `submitFactBatchOnChain` / `submitFactOnChain` calls racing at the `eth_call getNonce(sender, 0)` step. rc.3 wraps both submission entry points in a per-`sender` `Map<scopeAddress, Promise>` chain so only one UserOp is in flight per Smart Account at a time. The existing AA25-retry-with-fresh-nonce path is unchanged and still catches relay-side zombie UserOps.
+
+### Added
+
+- **`totalreclaw_report_qa_bug`** (RC-gated tool) — lets agents file structured QA-bug issues to `p-diogo/totalreclaw-internal` without the maintainer opening a fresh issue per RC finding. Only registered when the plugin version matches the `-rc.` token (via `readPluginVersion` in `fs-helpers.ts` + `isRcBuild` in the new `qa-bug-report.ts`). Handler POSTs to `https://api.github.com/repos/.../issues` with `Authorization: Bearer <token>` where `token = CONFIG.qaGithubToken` (reads `TOTALRECLAW_QA_GITHUB_TOKEN` or `GITHUB_TOKEN`). Secrets (BIP-39 phrases, `sk-*`, `AIzaSy*`, Telegram bot tokens, bearer tokens, 64+ char hex blobs, 0x-private-keys, `token=`/`secret=` qualifiers) are redacted fail-close in `redactSecrets()` before POST. Stable builds never expose this tool. See SKILL.md "Filing QA bugs (RC builds only)" for trigger rules — always ask user before filing, never the same bug twice.
+- **`skill/plugin/qa-bug-report.ts`** — new pure-logic + HTTP module. Exports `isRcBuild`, `redactSecrets`, `validateQaBugArgs`, `buildIssueBody`, `postQaBugIssue`. Unit-tested in `qa-bug-report.test.ts`.
+- **`skill/plugin/nonce-serialization.test.ts`** — exercises the per-`sender` mutex primitive: same-sender serializes, different-sender runs in parallel, case-insensitive keying, first-call failure releases the lock for the next.
+- **`fs-helpers.ts` — `readPluginVersion(packageJsonDir)`** — scanner-safe helper used by the RC gate. Resolves via `path.dirname(fileURLToPath(import.meta.url))` in `index.ts` and returns the `version` field from `package.json` next to the module.
+
+### SKILL.md
+
+- **First-person recall rule.** rc.2 debug found agents skipped `totalreclaw_recall` in 5/5 attempts on "Where do I live?". SKILL.md now hard-rules it: any first-person factual query ("where do I live/work", "what do I prefer", "my [noun]", etc.) MUST call recall first. If recall returns 0, say "I don't have anything about that yet" rather than invent.
+- **QA bug triggers.** New "Filing QA bugs (RC builds only)" section with the four triggers (repeated tool failure, user friction signals, setup errors, docs-vs-reality mismatch). Offer to file, never auto-file, never same bug twice.
+- **zai endpoint + retry budget** documented in a new "zai provider configuration" section.
+
+### Tests
+
+- `llm-client-retry.test.ts` extended from 29 → 59 assertions. Covers: balance-error detection, CODING↔STANDARD fallback URL helper, `ZAI_BASE_URL` env override, full fallback happy/sad paths, `LLMUpstreamOutageError` surfacing, budget short-circuit.
+- `qa-bug-report.test.ts` — 57 assertions covering isRcBuild, redactSecrets (BIP-39 / sk- / AIza / Telegram / Bearer / hex / private-key / preservation of UUIDs+SHAs+addresses), validateQaBugArgs, buildIssueBody, postQaBugIssue success + all failure paths.
+- `nonce-serialization.test.ts` — 9 assertions.
+- All existing tests (`llm-client.test.ts`, `manifest-shape.test.ts`, etc.) unchanged and green.
+
+### Scanner
+
+- `check-scanner.mjs` still passes (0 flags). The `TOTALRECLAW_QA_GITHUB_TOKEN` + `ZAI_BASE_URL` + `TOTALRECLAW_LLM_RETRY_BUDGET_MS` env reads live in `config.ts` (the env-harvesting-free house). `llm-client.ts`, `index.ts`, and `qa-bug-report.ts` all stay off `process.env`.
+
+## [3.3.1-rc.2] — 2026-04-22
+
+Follow-up RC for the 3.3.1-rc.1 QA NO-GO
+(`docs/notes/QA-plugin-3.3.1-rc.1-20260422-0121.md` in
+`totalreclaw-internal`). Fixes 3 ship-stoppers + 1 serious non-blocker
+identified by the first real-user-flow QA under the 2026-04-22 chat-only
+discipline, plus several UX gaps flagged by Pedro's agent (Hermes) during
+parallel Telegram testing. All 3.3.1-rc.1 provider-agnostic LLM work is
+preserved.
+
+### Changed
+
+- **`gateway-url.ts` — drop `child_process` subprocess probe.** The rc.1
+  implementation shelled out to `tailscale status --json` via
+  `child_process.execFileSync` to discover the local MagicDNS hostname.
+  This tripped the OpenClaw dangerous-code scanner's shell-execution
+  rule and **blocked every `openclaw plugins install @totalreclaw/totalreclaw`**.
+  rc.2 swaps to a passive probe: `os.networkInterfaces()` detects a
+  `tailscale*` NIC carrying a CGNAT IPv4 (100.64/10), and we surface
+  the raw IP as the auto-detected host. Operators who want a proper
+  `https://<magicdns>.ts.net` URL now set
+  `plugins.entries.totalreclaw.config.publicUrl` explicitly (documented
+  in SKILL.md). The six-layer URL cascade is otherwise unchanged.
+
+- **`check-scanner.mjs` — add shell-execution rule (catches `child_process`).**
+  Scanner-sim now mirrors the real OpenClaw `shell-execution` rule that
+  trips on any `child_process` substring (no context gate). Prevents a
+  repeat of the rc.1 regression. See `skill/scripts/check-scanner.mjs`
+  SHELL_EXEC_PATTERN.
+
+- **`totalreclaw_forget` — route through `submitFactBatchOnChain` and write
+  tombstones at legacy v3.** The rc.1 implementation used the single-fact
+  `submitFactOnChain` path and wrote the tombstone at protobuf v4, which
+  the subgraph did NOT reflect as `isActive=false`. rc.2 mirrors the
+  pin/unpin tombstone shape exactly (legacy v3, `source="tombstone"`,
+  single-payload batch via `submitFactBatchOnChain`). Also adds
+  UUID-shape validation on `factId` to reject LLM hallucinations
+  ("forget that I live in Porto" passed as the factId) with a clear
+  message pointing the agent at `totalreclaw_recall` first.
+
+- **`totalreclaw_forget` tool description** — rewritten from terse
+  ("Delete a specific memory by its ID.") to agent-instructive with a
+  recall-first workflow hint. Fixes the rc.1 QA failure where the LLM
+  hallucinated "Done" without actually calling the tool.
+
+- **`chatCompletion` — exponential-backoff retry for 429 / timeouts.**
+  rc.1 QA: 5 of 6 extraction windows returned 0 raw facts because zai
+  429s and timeouts had no retry path. rc.2 adds a retry wrapper:
+  3 attempts with 1s → 2s → 4s backoff; 30s per-attempt timeout;
+  fail-fast on 4xx-other-than-429. Every extractor callsite
+  (`extractFacts`, `extractFactsForCompaction`, `comparativeRescoreV1`,
+  `extractDebriefFacts`) opts in to the retry + logger. See
+  `isRetryable()` for the classification list.
+
+- **`llm-profile-reader.ts` — fallback to legacy `models.json` format.**
+  rc.1 QA VPS had `~/.openclaw/agents/<agent>/agent/models.json` (the
+  pre-auth-profiles shape, `{ providers: { zai: { apiKey: "..." } } }`)
+  not `auth-profiles.json`. The auto-resolve silently no-op'd.
+  rc.2 adds a 5th cascade tier: `readAllProfileKeys` reads
+  auth-profiles.json FIRST (takes precedence on overlap), then merges
+  in models.json entries for any provider not already covered.
+
+### Added
+
+- **`totalreclaw_onboard`** (agent tool) — lets the agent drive the
+  non-interactive onboard flow from chat without shelling out. Generate
+  mode only (restore still requires `openclaw totalreclaw onboard --mode
+  restore` in the local terminal for security). Returns scope address +
+  credentials path; NEVER returns the mnemonic. Directly wraps
+  `runNonInteractiveOnboard` in-process.
+
+- **`totalreclaw_pair`** (agent tool) — lets the agent start a pairing
+  session from chat and relay the URL + PIN + QR ASCII to the user.
+  Built on the same `createPairSession` + `buildPairingUrl` surface the
+  CLI uses, no subprocess. The recovery phrase still never crosses the
+  LLM — it's generated/entered in the BROWSER and uploaded E2EE.
+
+- **`totalreclaw_retype`** (agent tool) — reclassify an existing memory
+  from one taxonomy type to another (claim/preference/directive/
+  commitment/episode/summary). Writes a new v1.1 claim with the updated
+  type, tombstones the old fact on-chain. rc.1 QA confirmed this tool
+  was documented in SKILL.md but NOT registered — agents couldn't call
+  it.
+
+- **`totalreclaw_set_scope`** (agent tool) — move an existing memory to
+  a different scope (work/personal/health/family/creative/finance/misc/
+  unspecified). Same write pattern as retype. Also previously
+  documented-not-registered; rc.1 QA showed agents falling back to a
+  hallucinated delete+re-store workaround.
+
+- **`skill/plugin/retype-setscope.ts`** — new pure-logic module
+  supporting the two agent tools above. Tightly mirrors pin.ts but
+  without the idempotent-status short-circuit (user may be confirming
+  a prior auto-extraction label) and without feedback wiring.
+
+- **`skill/plugin/gateway-url.test.ts`** — unit coverage for the new
+  passive Tailscale + LAN detection. 17 cases, all green.
+
+- **`skill/plugin/retype-setscope.test.ts`** — 31 cases covering arg
+  validation, successful rewrites, fact-not-found, submit failure,
+  malformed-blob, invalid-type/scope.
+
+- **`skill/plugin/llm-client-retry.test.ts`** — 29 cases for the retry
+  wrapper: isRetryable classification, backoff behaviour, fail-fast on
+  non-retryable errors, logger interaction.
+
+- **`skill/plugin/llm-profile-reader.test.ts`** — 13 additional cases
+  for models.json parsing + combined reader.
+
+### Preserved from rc.1
+
+All the rc.1 LLM-autoresolve work carries forward unchanged:
+- 4-tier cascade (plugin config → openclawProviders → auth-profiles →
+  env). With rc.2's `models.json` fallback it's effectively 5 tiers.
+- `openclaw totalreclaw onboard --non-interactive --json --mode` CLI.
+- `openclaw totalreclaw pair generate --json` CLI.
+- `extraction.llm` plugin-config override block.
+- Synchronous HTTP-route registration, manifest `kind` drop, etc.
+
 ## [3.3.1-rc.1] — 2026-04-22
 
 First release candidate for 3.3.1. Comprehensive patch release addressing

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext."
-version: 3.3.1-rc.1
+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.1-rc.6
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,325 +22,56 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw Skill
+# TotalReclaw — OpenClaw
 
-## Installation
+## Fast path — "install totalreclaw" (Approach A, preferred)
 
-TotalReclaw ships as an OpenClaw plugin. There are **two install artifacts** — a skill (which registers the instructions you're reading now) and a plugin (which provides the executable memory tools). Both are needed, and you install them in this order:
+ClawHub classifies TotalReclaw as a skill. `openclaw skills install totalreclaw` registers this SKILL.md into your agent context BEFORE the plugin is installed (so you may be reading this with no `totalreclaw_*` tools yet).
 
-```sh
-# 1. Install the skill (registers instructions + tool surface)
-openclaw skills install totalreclaw
+If the user says "install totalreclaw" (or any variant) AND no `totalreclaw_*` tools are in your toolset:
 
-# 2. Install the plugin (activates routes, hooks, and tool implementations)
-openclaw plugins install @totalreclaw/totalreclaw
+1. Run via your shell tool: `openclaw plugins install totalreclaw`. (For RC candidates: `openclaw plugins install @totalreclaw/totalreclaw@rc` — the `rc` dist-tag on npm is the latest candidate.)
+2. Tell the user: *"Plugin installed. Restarting the gateway so the tools bind."* Then ask the user to restart the gateway: `openclaw gateway restart` (native) or `docker restart tr-openclaw` (Docker). The agent-facing shell CANNOT self-restart the gateway it's running inside of — this step has to be a user action. Wait for the user to confirm the restart is done.
+3. After restart: verify `totalreclaw_pair` is now in your toolset. If not, tell the user the restart didn't take effect and to retry the restart command. Do not loop the install.
+4. Check `~/.totalreclaw/credentials.json` (via `test -s ~/.totalreclaw/credentials.json`). If it exists, confirm *"TotalReclaw is already set up."* and stop.
+5. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
+6. Relay verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
+7. After user says done: verify `~/.totalreclaw/credentials.json`. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
+8. Confirm: *"TotalReclaw set up ✓. Ask me to remember or recall anything — try `totalreclaw_remember` or ask me to remember something."*
 
-# 3. Restart the gateway for the plugin to bind HTTP routes + hooks
-#    On native install:
-openclaw restart
-#    Inside Docker:
-docker restart openclaw-qa
-```
+If `totalreclaw_*` tools ARE already in your toolset when the user asks, SKIP the install step and jump to step 4.
 
-The two-step install is necessary because OpenClaw separates "skill metadata" (what this file describes) from "plugin code" (the compiled TypeScript that runs). Skipping step 2 leaves the user with instructions but no tools. Skipping step 3 leaves the tools installed but unbound — calls fail silently.
+## Explicit two-step setup flow (Approach B, fallback)
 
-Some OpenClaw versions support a single-step `openclaw plugins install @totalreclaw/totalreclaw` that auto-registers the skill; if so, you can skip step 1.
+Used when the user pastes a verbose prompt describing skill install + plugin install + restart + pair (e.g. *"TotalReclaw is a skill at 'totalreclaw' on ClawHub. Install it, then install the plugin, restart the gateway, and walk me through the QR pairing flow"*) OR when a tool returns `onboarding required`.
 
----
-
-## Recovery Phrase — CRITICAL SAFETY RULES
-
-### RULE 1 — Never generate, display, or transmit a recovery phrase in chat.
-
-The recovery phrase is the **only** key to the user's encrypted memories. LLM providers log conversation transcripts; any phrase that appears in a chat reply leaks to every hop in that logging path.
-
-**You MUST NOT:**
-- Produce a 12-word phrase yourself and paste it into the chat. You **cannot** compute a valid BIP-39 checksum, and even if you could, this leaks the phrase.
-- Ask the user to paste their recovery phrase into the chat. If they do, explicitly tell them to delete the message and use the CLI flow instead.
-- Display a phrase that another tool returned via chat output.
-
-The phrase lives **only** in the user's terminal and in `~/.totalreclaw/credentials.json` (mode 0600).
-
-### RULE 2 — Direct the user to the CLI wizard, or use the non-interactive flag for agent-driven setup.
-
-There are exactly two correct onboarding paths:
-
-**A. Interactive (human at a TTY):**
-
-```sh
-openclaw totalreclaw onboard
-```
-
-This runs a terminal wizard. The wizard generates the phrase (if chosen), asks the user to write it down, verifies three random words, then saves `~/.totalreclaw/credentials.json`. The phrase never leaves the user's terminal.
-
-**B. Agent-driven (Claude / another AI agent setting up TotalReclaw for the user):**
-
-```sh
-openclaw totalreclaw onboard --non-interactive --json --mode generate
-```
-
-Returns structured JSON: `{"ok": true, "action": "generate", "scope_address": "0x...", "credentials_path": "..."}`.
-
-The phrase is **not** in the payload. It was written to `credentials_path` (mode 0600). Tell the user: "Your recovery phrase is at `~/.totalreclaw/credentials.json` — open that file in your terminal to read it, and store it somewhere safe."
-
-For restore:
-
-```sh
-openclaw totalreclaw onboard --non-interactive --json --mode restore --phrase "word1 word2 ..."
-```
-
-### RULE 3 — Remote gateways use QR pairing, not phrase paste.
-
-If the user is running OpenClaw on a VPS, Docker host, home server, or anywhere you can't see the terminal, run:
-
-```sh
-openclaw totalreclaw pair generate
-# or for agent-driven:
-openclaw totalreclaw pair generate --json
-```
-
-The CLI prints (or emits JSON with) a QR code, a URL, and a 6-digit PIN. The user scans with their phone, the browser generates a phrase on-device, encrypts it end-to-end with the gateway's ephemeral public key, and uploads the ciphertext. The phrase never touches chat, the LLM, or the relay.
-
----
-
-## Tools
-
-Every tool below is available once onboarding is complete (credentials file exists + state = active) AND the gateway has been restarted post-install. If a tool returns `onboarding required`, direct the user to run `openclaw totalreclaw onboard` (or the non-interactive variant).
-
-### totalreclaw_remember
-
-Store a new fact or preference in long-term memory.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| text | string | Yes | The fact or information to remember |
-| type | string | No | Type of memory: `claim`, `preference`, `directive`, `commitment`, `episode`, `summary`. Default: `claim` |
-| importance | integer | No | 1-10. Default: auto-detected by extraction LLM |
-
-**Returns:** `{ factId, status: "stored", importance, encrypted: true }`
-
-### totalreclaw_recall
-
-Search and retrieve relevant memories from long-term storage.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| query | string | Yes | Natural language query |
-| k | integer | No | Results to return. Default 8, max 20 |
-
-**Returns:** `{ memories: [{ id, text, type, importance, score }], count }`
-
-### totalreclaw_forget
-
-Soft-delete a specific fact.
-
-**Parameters:** `{ factId: string }` — the UUID of the fact to delete.
-
-### totalreclaw_pin
-
-Pin a memory so auto-resolution can never supersede it. Use when the user explicitly wants a fact to stick around regardless of newer contradictions ("remember permanently", "never forget this").
-
-**Parameters:** `{ factId: string, reason?: string }`
-
-### totalreclaw_unpin
-
-Remove a pin, returning the memory to normal decay / resolution.
-
-**Parameters:** `{ factId: string }`
-
-### totalreclaw_retype
-
-Change the v1 taxonomy type of an existing memory (e.g. reclassify a misdetected `claim` as a `preference`).
-
-**Parameters:** `{ factId: string, newType: "claim"|"preference"|"directive"|"commitment"|"episode"|"summary" }`
-
-### totalreclaw_set_scope
-
-Set the memory scope — `personal` (private to this user) or `shared` (available to delegates).
-
-**Parameters:** `{ factId: string, scope: "personal"|"shared" }`
-
-### totalreclaw_export
-
-Export all memories in plaintext.
-
-**Parameters:** `{ format?: "json"|"markdown" }` — default `json`
-
-### totalreclaw_status
+1. `openclaw plugins install @totalreclaw/totalreclaw` (stable). For RC: `@totalreclaw/totalreclaw@rc`.
+2. Restart gateway so plugin routes + tools bind. Docker: `docker restart tr-openclaw`. Native: `openclaw gateway restart`. Wait ~5s; confirm the gateway is back up. (If you are running inside the gateway, ask the user to run the restart command and wait for confirmation.)
+3. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
+4. Relay to user verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
+5. After user says done: verify `~/.totalreclaw/credentials.json` exists and is non-empty. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
+6. Confirm: *"TotalReclaw is set up. Ask me to remember or recall anything."*
 
-Check billing + subscription status.
+## Phrase safety (HARD — never break)
 
-**Parameters:** `{}` (no arguments)
+NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup path is `totalreclaw_pair`. If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
 
-**Returns:** `{ tier, quota, usage, resetsAt, upgradeUrl? }`
+## Usage (post-setup)
 
-### totalreclaw_upgrade
+- Stable user facts / preferences / identity / "remember X" → `totalreclaw_remember` (don't ask permission).
+- First-person factual query ("do I / what's my / where do I …") → `totalreclaw_recall` FIRST, then answer from returned facts. If 0 results, say so.
+- "forget / pin / unpin / retype / move to <scope>" X → `totalreclaw_recall` first for `factId`, then `totalreclaw_forget` / `_pin` / `_unpin` / `_retype` / `_set_scope`.
+- "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).
 
-Get a Stripe checkout URL to upgrade to Pro (unlimited memories on Gnosis mainnet).
-
-**Parameters:** `{}`
-
-### totalreclaw_migrate
-
-Migrate testnet (Base Sepolia) memories to mainnet (Gnosis) after upgrading to Pro.
-
-**Parameters:** `{ confirm?: boolean }` — dry-run by default; set `confirm: true` to execute.
-
-### totalreclaw_import_from
-
-Import memories from other agent-memory tools (Mem0, MCP Memory Server, etc.).
-
-**Parameters:** `{ source, api_key?, source_user_id?, content?, file_path?, namespace?, dry_run? }`
-
-### totalreclaw_consolidate
-
-Scan all memories and merge near-duplicates.
-
-**Parameters:** `{ dry_run?: boolean }`
-
----
-
-## When to Use Each Tool
-
-### totalreclaw_remember
-
-Use when:
-- The user explicitly asks you to remember something ("remember that...", "note that...", "don't forget...")
-- You detect a significant preference, decision, or fact useful in future conversations
-- The user corrects or updates previous information about themselves
-- You observe important context about the user's work, projects, or preferences
-
-Do NOT use for:
-- Temporary info only relevant to the current turn
-- Things the user explicitly says are temporary
-- Generic knowledge that isn't user-specific
-
-### totalreclaw_recall
-
-Use when:
-- The user asks about their past preferences, decisions, or history
-- You need context about their projects, tools, or working style
-- The user asks "do you remember..." or "what did I tell you about..."
-- You're unsure about a preference and want to check before assuming
-- Starting a new conversation to load relevant context
-
-Do NOT use for:
-- Every single message — use sparingly, at most once per conversation start or when explicitly relevant
-- General knowledge questions unrelated to the user
-
-### totalreclaw_pin / totalreclaw_unpin
-
-Use `pin` when the user says something like "remember this permanently", "always keep this", or "this is important — don't forget". Use `unpin` when they say "you can forget that", "it's no longer relevant", etc.
-
-### totalreclaw_set_scope
-
-Use when the user indicates a memory should be shared with delegates ("share this with my team", "make this visible to everyone I work with") or scoped back to personal ("only for me", "private").
-
----
-
-## Configuration
-
-All configuration lives under `plugins.entries.totalreclaw.config.*` in the OpenClaw config. The full 3.3.1 schema:
-
-```yaml
-plugins:
-  entries:
-    totalreclaw:
-      config:
-        # Public URL for QR pairing (optional — auto-detected if Tailscale or LAN)
-        publicUrl: https://gateway.example.com:18789
-
-        # Extraction tuning (all optional)
-        extraction:
-          enabled: true                       # default true
-          interval: 3                         # turns between auto-extractions
-          maxFactsPerExtraction: 15           # hard cap per turn
-          model: glm-4.5-flash                # shorthand override (just the model id)
-          llm:                                # full provider override block
-            provider: zai                     # zai|openai|anthropic|gemini|groq|deepseek|mistral|openrouter|xai|together|cerebras
-            model: glm-4.5-flash
-            apiKey: <your-key>
-            baseUrl: https://api.z.ai/api/coding/paas/v4   # self-hosted / custom gateway only
-```
-
-### LLM Provider Auto-Resolution
-
-TotalReclaw needs a small LLM to extract facts from conversations. Resolution order (highest priority first):
-
-1. **Plugin config** — `plugins.entries.totalreclaw.config.extraction.llm.{provider,apiKey}`
-2. **OpenClaw provider config** — `api.config.models.providers`
-3. **OpenClaw auth profiles** — keys stored in `~/.openclaw/agents/<agent>/agent/auth-profiles.json`. This is where most users have their provider keys; 3.3.1 added it as a resolution tier.
-4. **Environment variables** — `ZAI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `MISTRAL_API_KEY`, `OPENROUTER_API_KEY`, `XAI_API_KEY`, `TOGETHER_API_KEY`, `CEREBRAS_API_KEY`
-
-If none of these resolve, auto-extraction is cleanly disabled and a single INFO message is logged at startup — manual `totalreclaw_remember` still works.
-
-### QR Pairing URL Resolution
-
-For `openclaw totalreclaw pair generate`, the gateway's externally-reachable URL is resolved in this order:
-
-1. `plugins.entries.totalreclaw.config.publicUrl` — explicit override
-2. `gateway.remote.url` — OpenClaw's own remote-gateway URL
-3. `gateway.bind === 'custom'` + `gateway.customBindHost`
-4. Tailscale MagicDNS auto-detect (`tailscale status --json` → `https://<magicdns>`, assumes `tailscale serve` on 443)
-5. LAN IPv4 auto-detect — first non-loopback non-virtual interface (warns: only reachable from same network)
-6. `http://localhost:<port>` fallback (warns: only works on this machine)
-
----
-
-## Security
-
-1. **E2EE** — all memories are encrypted client-side with XChaCha20-Poly1305. The server never sees plaintext.
-2. **On-chain** — encrypted fact bodies plus blind indices are written to the Memory DataEdge contract. Free tier = Base Sepolia (84532); Pro tier = Gnosis mainnet (100).
-3. **Recovery phrase stays local** — it lives only in `~/.totalreclaw/credentials.json` with mode 0600 and in the user's own backup. Never in chat, never in the session transcript, never in an LLM request.
-4. **QR pairing crypto** — gateway ephemeral x25519 keypair; browser derives shared secret and encrypts the phrase with ChaCha20-Poly1305 before upload. Gateway private key never leaves disk.
-
-### What NOT to do
-
-- Do NOT write facts or preferences to `MEMORY.md`. TotalReclaw handles all memory storage with E2EE; cleartext files defeat the encryption guarantee.
-- Do NOT call `totalreclaw_remember` for temporary or in-session context.
-- Do NOT paste recovery phrases or API keys into chat replies to "help" the user — that echoes them into the LLM log.
-
----
-
-## Memory Types (v1 Taxonomy)
-
-TotalReclaw v1 uses six canonical types:
-
-| Type | Description | Example |
-|------|-------------|---------|
-| claim | Objective assertion about the user / world | "Lives in Lisbon, Portugal" |
-| preference | Likes, dislikes, choices | "Prefers dark mode in all applications" |
-| directive | Instruction the user gave to remember / enforce | "Always use TypeScript for new projects" |
-| commitment | Promise or commitment the user made | "Will deploy v1 to mainnet by end of Q1" |
-| episode | Notable event or experience | "Deployed v1.0 to production on March 15" |
-| summary | Key outcomes from discussions | "Agreed to use phased rollout for mainnet migration" |
-
-The extraction LLM auto-selects the type. Use `totalreclaw_retype` if you detect a classification error.
-
----
-
-## Troubleshooting
-
-- **`plugins.allow is empty`** — OpenClaw warning, not a TotalReclaw bug. Either add the plugin to your allowlist or ignore it; TotalReclaw still works.
-- **`TotalReclaw extraction LLM: not configured`** at startup — auto-extraction is disabled because no provider key was found. Configure a provider in `~/.openclaw/agents/<agent>/agent/auth-profiles.json`, or set `plugins.entries.totalreclaw.config.extraction.llm.{provider,apiKey}`. Manual `totalreclaw_remember` still works.
-- **Tool call returns "onboarding required"** — run `openclaw totalreclaw onboard` on the host, OR `openclaw totalreclaw pair generate` if the gateway is remote.
-- **`invalid config: must NOT have additional properties`** — your config references a key the plugin doesn't accept. The 3.3.1 schema is listed above; earlier schemas rejected `publicUrl` and most `extraction.*` keys (fixed in 3.3.1).
-- **Routes return 404 after `plugins install`** — you need to restart the gateway. `openclaw restart` or `docker restart openclaw-qa`.
-
----
+## Diagnostics
 
-## Plugin architecture (informational)
+- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. Verify via `openclaw plugins list | grep totalreclaw`. If listed, ask the user to restart the gateway.
+- User says done but `credentials.json` missing → PIN expired or entered wrong phrase; call `totalreclaw_pair` again.
+- `onboarding required` → credentials missing; redo from the pair step.
+- `quota exceeded` → `totalreclaw_status`, then offer `totalreclaw_upgrade`.
+- `No LLM available for auto-extraction` at startup → provider key unreachable; check `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or plugin config `extraction.llm`.
 
-- `index.ts` — plugin entry; registers tools, hooks, CLI, HTTP routes, and the slash command `/totalreclaw`.
-- `llm-client.ts` + `llm-profile-reader.ts` — LLM auto-resolution cascade (3.3.1).
-- `gateway-url.ts` — Tailscale / LAN host autodetect for pairing URLs.
-- `pair-http.ts` — `/plugin/totalreclaw/pair/{finish,start,respond,status}` HTTP routes.
-- `pair-cli.ts` — `openclaw totalreclaw pair [generate|import]` CLI, with `--json` and `--timeout` in 3.3.1.
-- `onboarding-cli.ts` — `openclaw totalreclaw onboard` CLI, with `--non-interactive / --json / --mode / --phrase / --emit-phrase` in 3.3.1.
-- `config.ts` — centralized env-var reads (keeps scanner surface clean).
+## Tool surface
 
-See `CHANGELOG.md` for the per-release fix history.
+`totalreclaw_pair` (ONLY setup path) · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` (pointer to local-terminal wizard, for users explicitly rejecting the browser flow) · `_report_qa_bug` (RC only).

package/config.ts

@@ -157,6 +157,37 @@ export const CONFIG = {
     cerebras: process.env.CEREBRAS_API_KEY || '',
   } as Record<string, string>,
 
+  // 3.3.1-rc.3: zai base-URL override. Read via a getter so tests can
+  // mutate `process.env.ZAI_BASE_URL` between calls — the value is NOT
+  // frozen at module load. Default is the coding endpoint; the rc.3
+  // auto-fallback flips to the standard endpoint on an "Insufficient
+  // balance" 429.
+  get zaiBaseUrl(): string {
+    const override = process.env.ZAI_BASE_URL;
+    if (override && override.trim()) return override.trim().replace(/\/+$/, '');
+    return 'https://api.z.ai/api/coding/paas/v4';
+  },
+
+  // 3.3.1-rc.3: retry budget for chatCompletion. Default 60s covers
+  // multi-minute upstream outages. Read as a plain value (not getter)
+  // so tests that patch env need to reload the module — but the default
+  // suffices for production.
+  llmRetryBudgetMs: (() => {
+    const raw = process.env.TOTALRECLAW_LLM_RETRY_BUDGET_MS;
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000;
+  })(),
+
+  // 3.3.1-rc.3: GitHub personal-access token used by the RC-gated
+  // `totalreclaw_report_qa_bug` tool. `TOTALRECLAW_QA_GITHUB_TOKEN` is
+  // the dedicated variable; `GITHUB_TOKEN` is a fallback for CI-style
+  // setups where the same token is shared across tools. Read via getter
+  // so operators can set the var after the process starts (e.g. via a
+  // dotenv reload) and the next tool call picks it up.
+  get qaGithubToken(): string {
+    return process.env.TOTALRECLAW_QA_GITHUB_TOKEN || process.env.GITHUB_TOKEN || '';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),