@totalreclaw/totalreclaw 3.3.12-rc.9 → 3.3.12

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "End-to-end encrypted, decentralized memory for OpenClaw. Set up an account once, then call totalreclaw_remember / totalreclaw_recall (or the tr CLI under hybrid-primary) instead of writing to MEMORY.md / USER.md / local files. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any remember / recall request, AND any user statement that contains a preference / fact / decision / commitment about themselves."
-version: 3.3.12-rc.9
+description: "End-to-end encrypted, decentralized memory for OpenClaw. A native kind:memory provider — recall is automatic via memory_search/memory_get, and facts are captured in the background. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any recall request ('what do you remember about me', 'what's my X'), AND any explicit remember request ('remember X', 'save X')."
+version: 3.3.12-rc.23
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,55 +22,61 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — OpenClaw plugin
+# TotalReclaw — OpenClaw native memory provider
 
-End-to-end encrypted memory stored across a decentralized network (not on a single company server). The plugin handles install + account-setup autonomously; this skill tells the agent what to call and when.
+End-to-end encrypted memory stored across a decentralized network (not on a single company server). TotalReclaw is OpenClaw's **native `kind:"memory"` provider**: recall runs through the conventional `memory_search` / `memory_get` tools (the same surface `active-memory` uses), and **facts are captured automatically in the background** — you do not call a tool to remember each fact. This skill tells you the install + account-setup flow and when to drive recall explicitly.
 
-## TOP RULE — MEMORY STORAGE
+## How memory works here (read first)
 
-When the user states ANYTHING about themselves — preferences, decisions, identity, work, location, plans, tools, commitments — call `totalreclaw_remember` (or `tr remember --json "<fact>"` under hybrid-primary). NEVER write user facts to `MEMORY.md`, `USER.md`, or any local file. Those are agent-persona configuration; user memories live encrypted on-chain.
+- **Recall is native.** `memory_search` and `memory_get` are the memory tools. OpenClaw's `active-memory` sub-agent routes recall through them and the plugin injects guidance telling you when to search. When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `memory_search`. If 0 results, say so plainly — don't guess from session history.
+- **Capture is automatic.** The plugin extracts facts from the conversation in the background (trajectory poller). You do **not** call a tool on every preference/fact the user states — that happens for you. Never write user facts to `MEMORY.md`, `USER.md`, or any local file; those are agent-persona config, user memories live encrypted on-chain.
+- **Explicit remember only on request.** If the user explicitly says "remember X" / "save X" / "note X" / "don't forget X", use the CLI: `tr remember --json "X"`. One call per distinct fact.
 
-**Trigger immediately, no "should I?":** "I prefer / like / love / hate X", "my favorite is X", "I'm X", "my name is X", "I live / work at X", "I use X", "I decided X", "I'm going to X", "from now on X", "we agreed X", "I'll X by Y", "remind me to X", "remember that X", "save X", "note X". If a message contains MULTIPLE facts, call `totalreclaw_remember` once per fact — never blob.
-
-When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `totalreclaw_recall` FIRST. If 0 results, say so plainly — don't guess from session history.
-
-Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, `"local memory"`, `"local storage"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
+Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
 
 ## Phrase safety (HARD)
 
 The 12-word recovery phrase MUST NEVER enter chat or the agent's LLM context. The plugin's browser-based pair flow handles phrase generation and import. Never echo it, never ask the user to paste it, never pass it to any tool. If the user pastes one anyway, tell them it's compromised and re-pair for a fresh wallet.
 
+**HARD guardrail — install/reinstall/upgrade flows:** During install, reinstall, upgrade, or any verification steps, the agent MUST NOT read, list, cat, show, display, or inspect `credentials.json`, `~/.totalreclaw/credentials.json`, `~/.totalreclaw*/credentials.json`, `~/.openclaw/plugins/totalreclaw/credentials.json`, or ANY credentials/phrase/key/secrets file — for ANY reason, including "verifying the install." These files contain encryption key material and Smart Account addresses that MUST NOT enter the LLM context. Never run `ls`, `find`, `cat`, `show`, or similar commands against plugin directories to "check files."
+
 ## Install
 
 ```
-openclaw plugins install @totalreclaw/totalreclaw@rc
+openclaw plugins install @totalreclaw/totalreclaw
 openclaw skills install totalreclaw
 ```
 
-Plugin is published on npm + ClawHub (`p-diogo`, GitHub-verified). Stable: drop `@rc`. Under hybrid-primary, the `tr` CLI is the primary path; native `totalreclaw_*` tools are also bound when OpenClaw exposes them — use whichever your runtime binds.
-
-## Setup (plugin-driven)
+Published on npm + ClawHub (`p-diogo`, GitHub-verified). For a release candidate, pin with `@rc`; stable resolves from `latest`. The plugin self-applies any gateway config it needs on load and auto-reloads (see Restart below) — no manual gateway restart.
 
-The plugin auto-creates a pair session on first load when no credentials exist, writes `{url, pin, sid, expires_at_ms}` to `~/.totalreclaw/.pair-pending.json`, and injects a `before_agent_start` context block to you. **When you see that block, surface the URL and PIN to the user VERBATIM — read from the injected context; never invent values.** Confirm on pair completion: `✓ TotalReclaw set up.` (If credentials already exist: `✓ TotalReclaw is already set up.`)
+## Setup (pair — user-initiated QR)
 
-If a restart is needed (rare — plugin self-handles via gateway config-watcher), issue the literal slash command `/totalreclaw-restart`. Never `kill`, `docker restart`, or prompt the user to restart.
+Pairing is a deliberate, user-initiated QR flow (the plugin does **not** auto-pair on load). When credentials don't exist:
 
-## Hybrid-primary CLI
+1. Run `tr pair --json` → returns `{"url":"https://…/pair/p/<id>#pk=…","pin":"123456","expires_at_ms":…}`.
+2. Surface the **url** and **pin** to the user verbatim (read from the JSON; never invent values): "Open `<url>` in your browser, enter PIN `<pin>`, and generate or paste your 12-word recovery phrase. Reply done once it's sealed."
+3. The user completes in the browser (phrase is generated/imported browser-side, encrypted, posted to the relay — never touches this chat). On completion `~/.totalreclaw/credentials.json` is written.
+4. Confirm: `✓ TotalReclaw set up.` (If credentials already exist when first asked: `✓ TotalReclaw is already set up.`)
 
-OpenClaw 2026.5.x may strip non-bundled tool bindings (issue #223). Never rely on `totalreclaw_*` tool binding alone. Fall back via shell:
+Pair is UNCONDITIONAL when no credentials — the user installing/requesting setup IS the consent; do not add a second consent gate. `tr --help` lists every subcommand.
 
 ```bash
 TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-node "$TR_CLI" status --json     # {"version":"...","hybrid_mode":true,"tool_count":17}
-node "$TR_CLI" remember --json "I work at Graph Foundation"
-node "$TR_CLI" recall --json "where does the user work" --limit 5   # {"results":[{"text":"...","score":0.8}]}
-node "$TR_CLI" pair --json       # {"url":"...","pin":"123456","expires_at_ms":...} — plugin's auto-pair is preferred; only use this for re-pair
+node "$TR_CLI" pair --json        # start/re-pair
+node "$TR_CLI" status --json      # {"version":"…","paired":true,…}
 ```
 
-Pair is UNCONDITIONAL when no credentials — pasting the install URL IS the consent. `tr --help` lists every subcommand.
+## Restart (agent-driven, never user-manual)
+
+The plugin self-reloads: after install it writes the gateway config it needs and signals `SIGUSR1` to its own PID so the gateway picks it up without a manual restart. **If `memory_search`/`memory_get` are not bound** (tools didn't take effect on first load), issue the literal slash command `/totalreclaw-restart` **autonomously** — announce it in one line, never ask the user to authorize it, never stall, never `kill` / `docker restart` / prompt the user to restart. This mirrors the autonomous-restart pattern other runtimes use; the user should never perform a manual restart.
+
+## Tools + CLI surface
+
+**Recall (native memory contract — agent-facing):** `memory_search`, `memory_get`.
 
-## Tools (17 native; same surface via `tr`)
+**Explicit capture + curation (CLI — `tr`, i.e. `node "$TR_CLI" …`):**
+`tr remember` (explicit write) · `tr pin` / `tr unpin` · `tr retype` · `tr set_scope` · `tr status` · `tr export` · `tr pair`. Import + plan upgrade run via the gateway subcommand: `openclaw totalreclaw import from <source> --file <path> [--json]`, `openclaw totalreclaw upgrade [--json]`, `openclaw totalreclaw import status|abort`.
 
-`totalreclaw_remember` · `totalreclaw_recall` · `totalreclaw_forget` · `totalreclaw_pair` · `totalreclaw_pin` · `totalreclaw_unpin` · `totalreclaw_retype` · `totalreclaw_set_scope` · `totalreclaw_export` · `totalreclaw_import_from` · `totalreclaw_import_batch` · `totalreclaw_consolidate` · `totalreclaw_status` · `totalreclaw_upgrade` · `totalreclaw_migrate` · `totalreclaw_onboarding_start` · `totalreclaw_report_qa_bug` (RC only).
+The legacy `totalreclaw_*` agent tools and the `tr recall` CLI are retired — recall is `memory_search`, explicit capture is `tr remember`. If a stale guide references them, follow this SKILL instead.
 
-Full guides: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+Full guide: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>

package/api-client.ts

@@ -1,8 +1,9 @@
 /**
  * TotalReclaw Plugin - HTTP API Client
  *
- * Communicates with the TotalReclaw server over JSON/HTTP. Uses Node.js
- * built-in `fetch` (available since Node 18).
+ * Communicates with the TotalReclaw server over JSON/HTTP. All wire I/O
+ * goes through `relay.ts` (the plugin's single network site); this module
+ * owns request/response shape, status-checking, and error context.
  *
  * All authenticated endpoints expect:
  *   Authorization: Bearer <hex-encoded-auth-key>
@@ -16,6 +17,7 @@
  */
 
 import { buildRelayHeaders } from './relay-headers.js';
+import { relayFetch } from './relay.js';
 
 // ---------------------------------------------------------------------------
 // Request / Response Types
@@ -131,7 +133,8 @@ export function createApiClient(serverUrl: string) {
       authKeyHash: string,
       saltHex: string,
     ): Promise<{ user_id: string }> {
-      const res = await fetch(`${baseUrl}/v1/register`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/register`,
         method: 'POST',
         headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
@@ -165,7 +168,8 @@ export function createApiClient(serverUrl: string) {
       facts: StoreFactPayload[],
       authKeyHex: string,
     ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
-      const res = await fetch(`${baseUrl}/v1/store`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/store`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -203,7 +207,8 @@ export function createApiClient(serverUrl: string) {
       maxCandidates: number,
       authKeyHex: string,
     ): Promise<SearchCandidate[]> {
-      const res = await fetch(`${baseUrl}/v1/search`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/search`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -234,7 +239,8 @@ export function createApiClient(serverUrl: string) {
      * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
      */
     async deleteFact(factId: string, authKeyHex: string): Promise<void> {
-      const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/facts/${encodeURIComponent(factId)}`,
         method: 'DELETE',
         headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
@@ -259,7 +265,8 @@ export function createApiClient(serverUrl: string) {
      * @returns The number of facts that were actually deleted.
      */
     async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
-      const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/facts/batch-delete`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -295,7 +302,8 @@ export function createApiClient(serverUrl: string) {
       const params = new URLSearchParams({ limit: String(limit) });
       if (cursor) params.set('cursor', cursor);
 
-      const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/export?${params.toString()}`,
         method: 'GET',
         headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
@@ -325,7 +333,7 @@ export function createApiClient(serverUrl: string) {
      */
     async health(): Promise<boolean> {
       try {
-        const res = await fetch(`${baseUrl}/health`, { method: 'GET' });
+        const res = await relayFetch({ url: `${baseUrl}/health`, method: 'GET' });
         return res.status === 200;
       } catch {
         return false;

package/batch-gate.ts

@@ -0,0 +1,42 @@
+/**
+ * Boot-time chain-gate predicate for client-side `executeBatch` UserOp
+ * submission. Spec #281 §9 Phase 1 (item imp-16).
+ *
+ * The gate batches via `executeBatch` on Gnosis (chain 100). After ops-1
+ * (2026-06-05) BOTH tiers run on Gnosis, so both now batch — the chain==100
+ * check is retained as a safety guard (a non-100 chain, which shouldn't occur
+ * after ops-1, falls back to single-fact). The legacy Free ⇒ Base Sepolia
+ * (84532) single-fact path is gone with the retired two-tier routing (#402).
+ * The `TOTALRECLAW_GNOSIS_BATCH_ENABLED` env var is a hard kill-switch —
+ * setting it to `false` disables batching regardless of chain, so ops can
+ * revert to single-fact submission without a client redeploy. Behaviour of
+ * `shouldBatchOnChain` is unchanged by #402.
+ *
+ * Read at boot only (module-load time). Per-write reads would re-parse the
+ * env on every submission — too expensive for the auto-extraction hot path
+ * and pointless because the env doesn't change mid-process.
+ *
+ * Sibling work-leaves wire `shouldBatchOnChain` into `submitFactBatchOnChain`
+ * (TS) and `agent/lifecycle.py` (Python mirror in `batch_gate.py`); this
+ * module ships the primitive only.
+ *
+ * Env read is centralized in entry.ts (env-reading seam, Task 1.3 of the
+ * OpenClaw native integration plan, 2026-06-21).
+ */
+
+import { isGnosisBatchEnabledAtBoot } from './entry.js';
+
+const GNOSIS_CHAIN_ID = 100;
+
+export function shouldBatchOnChain(chainId: number): boolean {
+  if (!isGnosisBatchEnabledAtBoot()) return false;
+  return chainId === GNOSIS_CHAIN_ID;
+}
+
+export const __testing = {
+  readGateForTests(env: NodeJS.ProcessEnv, chainId: number): boolean {
+    const enabled = (env.TOTALRECLAW_GNOSIS_BATCH_ENABLED ?? '').toLowerCase() !== 'false';
+    if (!enabled) return false;
+    return chainId === GNOSIS_CHAIN_ID;
+  },
+};

package/billing-cache.ts

@@ -11,8 +11,12 @@
  * This module:
  *   - reads/writes `~/.totalreclaw/billing-cache.json` (path from CONFIG)
  *   - exports `BillingCache`, `BILLING_CACHE_PATH`, `BILLING_CACHE_TTL`
- *   - keeps the chain-id override in sync with the cached tier so Pro-tier
- *     UserOps sign against chain 100 and Free-tier stays on 84532
+ *   - keeps the chain-id override in sync with the relay's authoritative
+ *     `chain_id` (after ops-1 both tiers are on Gnosis 100; the client consumes
+ *     the relay value verbatim — see `syncChainIdFromBilling`)
+ *   - keeps the DataEdge-address override in sync with the relay's
+ *     authoritative `data_edge_address` (staging vs prod contract; consumed
+ *     verbatim — see `syncDataEdgeAddressFromBilling`, #460)
  *   - does NOT import anything that performs outbound I/O
  *
  * Do NOT add any outbound-request call to this file — a single match for
@@ -23,7 +27,10 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { CONFIG, setChainIdOverride } from './config.js';
+import { CONFIG, setChainIdOverride, setDataEdgeAddressOverride } from './config.js';
+
+/** A plausible EVM address — anything else from billing is ignored (#460). */
+const DATA_EDGE_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -50,6 +57,19 @@ export interface BillingCache {
     max_facts_per_extraction?: number;
     max_candidate_pool?: number;
   };
+  /**
+   * Authoritative chain id from the relay `/v1/billing/status` response.
+   * After ops-1 (2026-06-05) both tiers are on Gnosis (100); the relay is the
+   * source of truth, so the client consumes this verbatim (#402).
+   */
+  chain_id?: number;
+  /**
+   * Authoritative DataEdge contract address from the relay
+   * `/v1/billing/status` response. Staging returns the isolated staging
+   * DataEdge, production the prod DataEdge; the client consumes this verbatim
+   * so writes and reads land on the same contract (#460).
+   */
+  data_edge_address?: string;
   checked_at: number;
 }
 
@@ -58,24 +78,49 @@ export interface BillingCache {
 // ---------------------------------------------------------------------------
 
 /**
- * Apply the billing tier to the runtime chain override.
+ * Apply the relay's authoritative `chain_id` to the runtime chain override.
  *
- * Pro tier → chain 100 (Gnosis mainnet). Free tier (or unknown) stays on
- * 84532 (Base Sepolia). The relay routes Pro UserOps to Gnosis, so the
- * client MUST sign them against chain 100 — otherwise the bundler returns
- * AA23 (invalid signature). See MCP's equivalent path in mcp/src/index.ts.
+ * After ops-1 (2026-06-05) both tiers run on Gnosis (chain 100) and the relay
+ * returns an authoritative `chain_id` in `/v1/billing/status`. The client MUST
+ * consume that verbatim — the old tier→chain derivation (Free ⇒ 84532 Base
+ * Sepolia) was retired two-tier logic that mis-signed FREE-tier UserOps
+ * against the wrong chain and queried a Base-Sepolia RPC for a Gnosis-deployed
+ * sender, producing deterministic AA10 (#402).
  *
- * Called from `readBillingCache` and `writeBillingCache` so that every cache
- * read or write keeps the chain override in sync with the cached tier.
- * Idempotent — calling with the same tier is a no-op.
+ * A missing / non-finite `chain_id` (older relay, partial payload) defaults to
+ * 100 — never 84532. Called from `readBillingCache` and `writeBillingCache` so
+ * every cache read or write keeps the override in sync. Idempotent.
  */
-export function syncChainIdFromTier(tier: string | undefined): void {
-  if (tier === 'pro') {
-    setChainIdOverride(100);
-  } else {
-    // Free or unknown → reset to the default free-tier chain.
-    setChainIdOverride(84532);
-  }
+export function syncChainIdFromBilling(chainId: number | undefined): void {
+  setChainIdOverride(typeof chainId === 'number' && Number.isFinite(chainId) ? chainId : 100);
+}
+
+// ---------------------------------------------------------------------------
+// DataEdge-address sync
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply the relay's authoritative `data_edge_address` to the runtime DataEdge
+ * override. Mirrors `syncChainIdFromBilling`.
+ *
+ * The relay routes each environment to its own DataEdge (staging is on-chain
+ * isolated). If the client ignores this and uses the WASM-baked default (the
+ * PROD DataEdge), writes against the staging relay mine on the prod contract
+ * while reads come from the staging subgraph → empty recall + phantom
+ * "stored=N" success (#460).
+ *
+ * A missing / malformed `data_edge_address` (older relay, partial payload,
+ * junk) clears the override (`null`) so resolution falls through to the WASM
+ * default — never a stale value. Only a plausible address
+ * (`0x` + 40 hex) is honored. Called from `readBillingCache` and
+ * `writeBillingCache` so every cache read or write keeps the override in sync.
+ * Idempotent. The explicit env override (`TOTALRECLAW_DATA_EDGE_ADDRESS`)
+ * still wins — it is the first term in `getSubgraphConfig`.
+ */
+export function syncDataEdgeAddressFromBilling(address: string | undefined): void {
+  setDataEdgeAddressOverride(
+    typeof address === 'string' && DATA_EDGE_ADDRESS_RE.test(address) ? address : null,
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -95,8 +140,10 @@ export function readBillingCache(): BillingCache | null {
     if (!fs.existsSync(BILLING_CACHE_PATH)) return null;
     const raw = JSON.parse(fs.readFileSync(BILLING_CACHE_PATH, 'utf-8')) as BillingCache;
     if (!raw.checked_at || Date.now() - raw.checked_at > BILLING_CACHE_TTL) return null;
-    // Keep chain override in sync with persisted tier across process restarts.
-    syncChainIdFromTier(raw.tier);
+    // Keep chain + DataEdge overrides in sync with the persisted authoritative
+    // values across process restarts.
+    syncChainIdFromBilling(raw.chain_id);
+    syncDataEdgeAddressFromBilling(raw.data_edge_address);
     return raw;
   } catch {
     return null;
@@ -116,7 +163,9 @@ export function writeBillingCache(cache: BillingCache): void {
   } catch {
     // Best-effort — don't block on cache write failure.
   }
-  // Sync chain override AFTER the write so in-process UserOp signing picks
-  // up the correct chain immediately, even if the disk write failed.
-  syncChainIdFromTier(cache.tier);
+  // Sync chain + DataEdge overrides AFTER the write so in-process UserOp
+  // signing + subgraph reads pick up the correct chain and contract
+  // immediately, even if the disk write failed.
+  syncChainIdFromBilling(cache.chain_id);
+  syncDataEdgeAddressFromBilling(cache.data_edge_address);
 }

package/claims-helper.ts

@@ -30,6 +30,7 @@ import {
   VALID_MEMORY_VOLATILITIES,
   VALID_MEMORY_TYPES_V1,
 } from './extractor.js';
+import { envStringLower } from './entry.js';
 
 // Lazy-load WASM. We use createRequire so this module loads cleanly under
 // both the OpenClaw runtime (CJS-ish tsx) and bare Node ESM (used by tests).
@@ -640,7 +641,7 @@ export type AutoResolveMode = 'active' | 'off' | 'shadow';
  * @internal Not public config — emergency kill-switch only.
  */
 export function resolveAutoResolveMode(): AutoResolveMode {
-  const raw = (process.env.TOTALRECLAW_AUTO_RESOLVE_MODE ?? '').trim().toLowerCase();
+  const raw = envStringLower('TOTALRECLAW_AUTO_RESOLVE_MODE');
   if (raw === 'off') return 'off';
   if (raw === 'shadow') return 'shadow';
   return 'active';

package/config.ts

@@ -102,10 +102,10 @@ export function getSessionId(): string | null {
 
 /**
  * Runtime override for chain ID, set after the relay billing response is
- * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
- * (Gnosis mainnet). The relay routes Pro writes to Gnosis, so Pro-tier
- * UserOps MUST be signed against chain 100 — otherwise the bundler rejects
- * the signature with AA23.
+ * read. After the ops-1 single-chain migration (2026-05), ALL tiers (free
+ * + Pro) are on Gnosis mainnet (chain 100). The default below is 100.
+ * The relay routes all writes to Gnosis, so UserOps MUST be signed against
+ * chain 100 — otherwise the bundler rejects the signature with AA24.
  *
  * See index.ts: after the billing lookup completes, call
  * `setChainIdOverride(100)` for Pro users. Free users can leave the
@@ -122,6 +122,39 @@ export function __resetChainIdOverrideForTests(): void {
   _chainIdOverride = null;
 }
 
+/**
+ * Runtime override for the DataEdge contract address, set after the relay
+ * billing response is read. The relay returns an authoritative
+ * `data_edge_address` in `/v1/billing/status` (staging routes to the isolated
+ * staging DataEdge, production to the prod DataEdge). Chain-aware clients MUST
+ * consume it verbatim — otherwise writes mine on the WASM-baked prod DataEdge
+ * while reads hit the relay's subgraph, so recall silently returns empty
+ * against staging (#460). Mirrors `_chainIdOverride`.
+ *
+ * `null` means "no billing override" → fall through to the WASM default. The
+ * explicit operator env override (`TOTALRECLAW_DATA_EDGE_ADDRESS`, exposed as
+ * `CONFIG.dataEdgeAddress`) always wins over this.
+ */
+let _dataEdgeAddressOverride: string | null = null;
+
+export function setDataEdgeAddressOverride(address: string | null): void {
+  _dataEdgeAddressOverride = address;
+}
+
+/**
+ * Read the billing-sourced DataEdge override (or `''` when unset). Used by
+ * `getSubgraphConfig` as the middle term of the env → billing → WASM-default
+ * resolution order (#460).
+ */
+export function getDataEdgeAddressOverride(): string {
+  return _dataEdgeAddressOverride ?? '';
+}
+
+/** Reset the DataEdge override — used by tests. */
+export function __resetDataEdgeAddressOverrideForTests(): void {
+  _dataEdgeAddressOverride = null;
+}
+
 export const CONFIG = {
   // Core — recoveryPhrase reads from override first, then env var.
   // Use getRecoveryPhrase() for dynamic access; this property is for
@@ -148,6 +181,42 @@ export const CONFIG = {
   serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
   selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
   credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
+  // cred-3 stage 1 — credential-provider abstraction.
+  //
+  // `file` (default) preserves the legacy behavior: read/write
+  // `credentialsPath` directly via fs-helpers.
+  //
+  // `external` instructs the plugin to load credentials from an
+  // out-of-process source at boot. Two transports are supported (mutually
+  // exclusive — JSON wins if both set):
+  //   1. `externalCredentialsJson` — raw JSON string of CredentialsFile,
+  //      injected at process start by the secret manager (Railway secrets,
+  //      Docker `--env-file`, K8s envFrom). Most ergonomic for cloud
+  //      deployments where the secret manager already exposes secrets as
+  //      env vars.
+  //   2. `externalCredentialsPath` — filesystem path to a JSON file the
+  //      secret manager mounts (Docker Compose `secrets:` block,
+  //      K8s secret volumeMount, tmpfs populated by an ops wrapper that
+  //      fetches from AWS Secrets Manager / Hetzner Vault before boot).
+  //
+  // `external` mode is read-only: write/clear are no-ops with a warning
+  // (the secret manager owns the source of truth — the plugin must not
+  // write back through this path).
+  //
+  // See `docs/guides/production-deployment.md` for the LUKS / dm-crypt
+  // pattern and managed-secret-store wiring examples.
+  credentialsProvider: (() => {
+    const v = (process.env.TOTALRECLAW_CREDENTIALS_PROVIDER ?? '').trim().toLowerCase();
+    return v === 'external' ? 'external' : 'file';
+  })() as 'file' | 'external',
+  externalCredentialsJson: (() => {
+    const v = (process.env.TOTALRECLAW_EXTERNAL_CREDENTIALS_JSON ?? '').trim();
+    return v.length > 0 ? v : null;
+  })() as string | null,
+  externalCredentialsPath: (() => {
+    const v = (process.env.TOTALRECLAW_EXTERNAL_CREDENTIALS_PATH ?? '').trim();
+    return v.length > 0 ? v : null;
+  })() as string | null,
   // 3.2.0 onboarding state file — separate from credentials.json so it
   // never contains secrets. Loaded on every plugin init + on every
   // before_tool_call gate check.
@@ -185,21 +254,28 @@ export const CONFIG = {
       : 'wss://api.totalreclaw.xyz')
   ).replace(/\/+$/, ''),
 
-  // Chain — chainId is no longer user-configurable. It is auto-detected from
-  // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
-  // 100). The default here is used only before the first billing lookup
+  // Chain — chainId is no longer user-configurable. After the ops-1 single-
+  // chain migration, ALL tiers are on Gnosis (100). The default here is 100.
   // completes. Self-hosted users can still point at a custom DataEdge via
   // TOTALRECLAW_DATA_EDGE_ADDRESS / TOTALRECLAW_ENTRYPOINT_ADDRESS /
   // TOTALRECLAW_RPC_URL (undocumented; internal knobs).
   //
-  // Reads the runtime override set by the billing auto-detect in index.ts.
-  // Falls back to 84532 (free tier / pre-billing-lookup). Must be a getter,
-  // not a literal — a literal would freeze all Pro-tier UserOps to the
-  // wrong chainId and AA23 at the bundler.
+  // Reads the runtime override set from the relay's authoritative chain_id
+  // (syncChainIdFromBilling). Falls back to 100 (Gnosis) pre-billing-lookup —
+  // after ops-1 both tiers are on Gnosis, so 84532 is never the default (#402).
+  // Must be a getter, not a literal — a literal would freeze UserOps to the
+  // wrong chainId and fail signature validation at the bundler.
   get chainId(): number {
-    return _chainIdOverride ?? 84532;
+    return _chainIdOverride ?? 100;
+  },
+  // Explicit operator env override for the DataEdge contract. Stays env-only:
+  // it is the FIRST term of `getSubgraphConfig`'s env → billing → WASM-default
+  // resolution order, so it wins over the relay's authoritative
+  // `data_edge_address` (see `getDataEdgeAddressOverride` / #460). Getter, not
+  // a literal, so it reflects the live env rather than freezing at module load.
+  get dataEdgeAddress(): string {
+    return process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '';
   },
-  dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
   entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
   rpcUrl: process.env.TOTALRECLAW_RPC_URL || '',
 
@@ -224,6 +300,12 @@ export const CONFIG = {
   // See: docs/specs/totalreclaw/client-consistency.md
   cosineThreshold: parseFloat(process.env.TOTALRECLAW_COSINE_THRESHOLD ?? '0.15'),
   extractInterval: parseInt(process.env.TOTALRECLAW_EXTRACT_INTERVAL ?? process.env.TOTALRECLAW_EXTRACT_EVERY_TURNS ?? '3', 10),
+  // Self-hosted fallback for max-facts-per-extraction. `undefined` when the
+  // env var is unset so getMaxFactsPerExtraction() can fall through to the
+  // billing cache then the built-in MAX_FACTS_PER_EXTRACTION constant.
+  maxFactsPerExtraction: process.env.TOTALRECLAW_MAX_FACTS_PER_EXTRACTION
+    ? parseInt(process.env.TOTALRECLAW_MAX_FACTS_PER_EXTRACTION, 10)
+    : undefined,
   relevanceThreshold: parseFloat(process.env.TOTALRECLAW_RELEVANCE_THRESHOLD ?? '0.3'),
   semanticSkipThreshold: parseFloat(process.env.TOTALRECLAW_SEMANTIC_SKIP_THRESHOLD ?? '0.85'),
   cacheTtlMs: parseInt(process.env.TOTALRECLAW_CACHE_TTL_MS ?? String(5 * 60 * 1000), 10),

package/consolidation.ts

@@ -18,11 +18,14 @@
  * and `clusterFacts` WASM functions when available, falling back to local
  * implementations that use WASM-backed `cosineSimilarity`.
  *
- * Threshold helpers remain local (they read process.env).
+ * Threshold helpers remain local; their env reads are centralized in
+ * entry.ts (env-reading seam, Task 1.3 of the OpenClaw native
+ * integration plan, 2026-06-21).
  */
 
 import { createRequire } from 'node:module';
 import { cosineSimilarity } from './reranker.js';
+import { envNumber } from './entry.js';
 
 // ---------------------------------------------------------------------------
 // Lazy-load WASM core (mirrors claims-helper.ts / contradiction-sync.ts
@@ -47,12 +50,7 @@ function getWasm(): typeof import('@totalreclaw/core') {
  * Must be a number in [0, 1]. Falls back to 0.85 if invalid or unset.
  */
 export function getStoreDedupThreshold(): number {
-  const envVal = process.env.TOTALRECLAW_STORE_DEDUP_THRESHOLD;
-  if (envVal !== undefined) {
-    const parsed = parseFloat(envVal);
-    if (!isNaN(parsed) && parsed >= 0 && parsed <= 1) return parsed;
-  }
-  return 0.85;
+  return envNumber('TOTALRECLAW_STORE_DEDUP_THRESHOLD', 0.85, { min: 0, max: 1 });
 }
 
 /**
@@ -62,12 +60,7 @@ export function getStoreDedupThreshold(): number {
  * Must be a number in [0, 1]. Falls back to 0.88 if invalid or unset.
  */
 export function getConsolidationThreshold(): number {
-  const envVal = process.env.TOTALRECLAW_CONSOLIDATION_THRESHOLD;
-  if (envVal !== undefined) {
-    const parsed = parseFloat(envVal);
-    if (!isNaN(parsed) && parsed >= 0 && parsed <= 1) return parsed;
-  }
-  return 0.88;
+  return envNumber('TOTALRECLAW_CONSOLIDATION_THRESHOLD', 0.88, { min: 0, max: 1 });
 }
 
 /** Maximum candidates to compare against during store-time dedup. */