@totalreclaw/totalreclaw 3.3.1-rc.18 → 3.3.1-rc.19

package/SKILL.md

@@ -30,8 +30,8 @@ ClawHub classifies TotalReclaw as a skill. `openclaw skills install totalreclaw`
 
 If the user says "install totalreclaw" (or any variant) AND no `totalreclaw_*` tools are in your toolset:
 
-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.
+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.) If the shell call fails with `command not found` / ENOENT / "not authorized" / similar (managed-service or shell-restricted environment): tell the user *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+2. Tell the user verbatim: *"Plugin installed. Please restart your OpenClaw gateway so the new tools bind. Common patterns: `openclaw gateway restart` (native install), `docker restart <your-container-name>` (Docker self-host — substitute your actual container name; `docker ps` will show it), or use your managed service's restart control if you're on a hosted plan. Once the gateway is back up, reply `done` and I'll continue."* Do NOT invoke any restart command yourself — your shell is running inside the gateway you're restarting (catch-22). Wait for the user's `done` before proceeding.
 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, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR on your transport" below for the rc.5+ additions).
@@ -45,8 +45,8 @@ If `totalreclaw_*` tools ARE already in your toolset when the user asks, SKIP th
 
 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`.
 
-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.)
+1. `openclaw plugins install @totalreclaw/totalreclaw` (stable). For RC: `@totalreclaw/totalreclaw@rc`. If the CLI isn't available to your shell (managed service / shell-restricted env): ask the user to install `totalreclaw` from their service's plugins UI and reply `done`.
+2. Restart gateway so plugin routes + tools bind. Tell the user verbatim: *"Please restart your gateway: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host — replace with your actual container name), or your managed service's restart control. Reply `done` once it's back up."* Do NOT run the restart yourself — your shell is inside the gateway. Wait for the user's `done`.
 3. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR on your transport" below for the rc.5+ additions).
 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.
@@ -66,7 +66,7 @@ The QR encodes ONLY the pair URL. The 6-digit PIN is a separate out-of-band conf
 
 ## Phrase safety (HARD — never break)
 
-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 paths are (in order of preference): (1) `totalreclaw_pair` tool; (2) if the tool is missing from your tool list — a known gap for some container-based agents, issue #87 — shell out to `openclaw totalreclaw pair generate --url-pin-only`, which emits a single-line JSON `{v,url,pin,expires_at_ms}` with zero phrase material on stdout (pair-crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
+NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard` (the bare interactive form), `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup paths are (in order of preference): (1) `totalreclaw_pair` tool; (2) if the tool is missing from your tool list — a known gap for some container-based agents, issue #87 — shell out to EITHER `openclaw totalreclaw pair generate --url-pin-only` (single-line JSON `{v,url,pin,expires_at_ms}`) OR `openclaw totalreclaw onboard --pair-only` (single-line JSON `{v,pair_url,pin,expires_at_ms}`, issue #95 — same pair flow, `pair_url` key naming). Both have zero phrase material on stdout (pair-crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
 
 ## Usage (post-setup)
 
@@ -78,7 +78,7 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 
 ## Diagnostics
 
-- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. Verify via `openclaw plugins list | grep totalreclaw`. If listed but tools still absent (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 — do NOT suggest `openclaw totalreclaw onboard` (leaks phrase on stdout).
+- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. 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 listed but tools still absent (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).
 - 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`.

package/index.ts

@@ -2902,6 +2902,12 @@ const plugin = {
             credentialsPath: CREDENTIALS_PATH,
             statePath: CONFIG.onboardingStatePath,
             logger: api.logger,
+            // 3.3.1-rc.18 — wire the pair flow into onboard so the
+            // `--pair-only` flag (issue #95) can delegate to it without
+            // duplicating session-store / URL-builder logic. Same deps
+            // as the standalone `pair` subcommand.
+            pairSessionsPath: CONFIG.pairSessionsPath,
+            renderPairingUrl: (session) => buildPairingUrl(api, session),
             // 3.3.1 — supplied to the non-interactive --json onboard path
             // so the emitted payload includes the derived Smart Account
             // (scope) address. Uses the chain-id default; Pro-tier

package/onboarding-cli.ts

@@ -59,6 +59,23 @@ import {
 // has one place to grow into later).
 // ---------------------------------------------------------------------------
 
+/**
+ * 3.3.1-rc.18 (issue #95) — deprecation warning for the interactive
+ * phrase-print branch. Emitted to STDERR (never stdout) so it is visible
+ * to humans but does not pollute any pipe consuming the wizard's output.
+ *
+ * The phrase-print branch will be REMOVED in the next RC after rc.18.
+ * Users running on a TTY can still complete the flow in rc.18; agents
+ * MUST use `--pair-only` or the `totalreclaw_pair` tool today.
+ */
+export const PHRASE_PRINT_DEPRECATION_WARNING =
+  '\nDEPRECATION (issue #95): the interactive `openclaw totalreclaw onboard` flow\n' +
+  '  prints your recovery phrase to this terminal. This is being removed in the\n' +
+  '  next release candidate. For agent / scripted invocation, use:\n' +
+  '    openclaw totalreclaw onboard --pair-only\n' +
+  '  which emits ONLY {pair_url, pin} JSON and routes the phrase through the\n' +
+  '  browser flow (never on stdout).\n\n';
+
 export const COPY = {
   welcome:
     '\nTotalReclaw — Secure onboarding\n\n' +
@@ -403,6 +420,11 @@ export async function runOnboardingWizard(deps: WizardDeps): Promise<WizardResul
   }
 
   if (choice === 'generate') {
+    // 3.3.1-rc.18 (issue #95) — deprecation banner on stderr ONLY.
+    // The phrase-print branch is scheduled for removal in the RC after
+    // rc.18; we keep it functional in rc.18 for back-compat with users
+    // running the wizard on a real TTY today.
+    io.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
     io.stdout.write(COPY.generateWarning);
     io.stdout.write(COPY.importRemoteLimitation);
     const mnemonic = genMnemonic();
@@ -674,6 +696,22 @@ export async function runNonInteractiveOnboard(
  *   --emit-phrase          Include the plaintext phrase in the JSON payload
  *                          (NOT recommended — the phrase lives in
  *                          credentials.json; prefer reading it there).
+ *
+ * 3.3.1-rc.18 — `onboard` accepts:
+ *   --pair-only            Phrase-safe agent-shell flag (issue #95).
+ *                          Delegates to the pair flow and emits a single
+ *                          line of JSON `{v, pair_url, pin, expires_at_ms}`
+ *                          to stdout. Phrase NEVER touches stdout, stderr,
+ *                          or the logger in this mode. Use this for any
+ *                          agent-driven setup; it is the recommended path
+ *                          when a container-based agent does not have the
+ *                          `totalreclaw_pair` tool injected.
+ *
+ *                          Requires `pairSessionsPath` + `renderPairingUrl`
+ *                          to be supplied to `registerOnboardingCli`. If
+ *                          absent, `--pair-only` exits non-zero with a
+ *                          clear message instead of falling through to the
+ *                          phrase-print branch.
  */
 export function registerOnboardingCli(
   program: import('commander').Command,
@@ -683,6 +721,10 @@ export function registerOnboardingCli(
     logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
     /** Caller-supplied helper for scope-address derivation. Optional — when absent, JSON output omits `scope_address`. */
     deriveScopeAddress?: (mnemonic: string) => Promise<string | undefined>;
+    /** Caller-supplied path to the pair-session store. Required for `--pair-only`. */
+    pairSessionsPath?: string;
+    /** Caller-supplied URL renderer for the pair flow. Required for `--pair-only`. */
+    renderPairingUrl?: (session: import('./pair-session-store.js').PairSession) => string;
   },
 ): void {
   const tr = program
@@ -690,12 +732,13 @@ export function registerOnboardingCli(
     .description('TotalReclaw encrypted memory — secure onboarding + status');
 
   tr.command('onboard')
-    .description('Interactive onboarding: generate or import a recovery phrase (runs locally, no LLM)')
+    .description('Interactive onboarding: generate or import a recovery phrase (runs locally, no LLM). For agent-driven setup prefer --pair-only.')
     .option('--non-interactive', 'Exit non-zero if any input would be prompted for (agent-driven use)')
     .option('--json', 'Emit the result as a structured JSON payload. Only valid with --non-interactive.')
     .option('--mode <mode>', 'generate | restore — skip the menu prompt')
     .option('--phrase <phrase>', 'Recovery phrase for --mode restore. `-` reads from stdin.')
     .option('--emit-phrase', 'Include the plaintext phrase in the JSON payload (not recommended). Default: false.')
+    .option('--pair-only', 'Phrase-safe agent-invocation mode (issue #95). Emits ONLY {v,pair_url,pin,expires_at_ms} JSON to stdout via the pair flow. Phrase never touches stdout/stderr/logger. RECOMMENDED for any agent or scripted invocation.')
     .action(async (...actionArgs: unknown[]) => {
       // commander: (options, cmd)
       const cliOpts = (actionArgs[0] ?? {}) as {
@@ -704,8 +747,70 @@ export function registerOnboardingCli(
         mode?: string;
         phrase?: string;
         emitPhrase?: boolean;
+        pairOnly?: boolean;
       };
 
+      // ---------------------------------------------------------------
+      // 3.3.1-rc.18 — `--pair-only` (issue #95)
+      //
+      // Phrase-safe agent-shell flag. Delegates to the pair flow and
+      // emits a single line of JSON `{v, pair_url, pin, expires_at_ms}`
+      // to stdout. By construction:
+      //   - The pair flow is x25519-only — pair-crypto.ts does NOT
+      //     import @scure/bip39 and never touches a recovery phrase.
+      //   - No interactive prompts, no readline, no @scure/bip39 import
+      //     in this code path. Phrase never enters stdout/stderr/logger.
+      //   - Stays silent on status transitions (the runPairCli
+      //     `pair-only` output mode suppresses banners, spinners, and
+      //     all human-readable copy).
+      //
+      // This MUST be the path agents take when they need to set up
+      // TotalReclaw via a shell. The interactive phrase-print branch
+      // below is deprecated for that use case and emits a warning when
+      // the user falls through to it.
+      // ---------------------------------------------------------------
+      if (cliOpts.pairOnly) {
+        if (!opts.pairSessionsPath || !opts.renderPairingUrl) {
+          process.stderr.write(
+            '--pair-only is unavailable: this OpenClaw build did not wire the pair flow into the onboard CLI. ' +
+              'Use `openclaw totalreclaw pair generate --url-pin-only` instead.\n',
+          );
+          process.exit(1);
+        }
+        // Resolve mode. --mode restore is incompatible with --pair-only
+        // since pair flow's "import" mode runs in the browser, not in
+        // the CLI. Default to 'generate' silently.
+        const pairMode = cliOpts.mode === 'restore' || cliOpts.mode === 'import' ? 'import' : 'generate';
+
+        // Lazy import — keeps pair-cli + qrcode-terminal off the
+        // onboarding hot path when --pair-only is not used.
+        const { runPairCli, defaultRenderQr, buildDefaultPairCliIo } = await import('./pair-cli.js');
+        const io = buildDefaultPairCliIo();
+        try {
+          const outcome = await runPairCli(pairMode, {
+            sessionsPath: opts.pairSessionsPath,
+            renderPairingUrl: opts.renderPairingUrl,
+            renderQr: defaultRenderQr,
+            io,
+            outputMode: 'pair-only',
+          });
+          if (outcome.status !== 'completed') {
+            process.exit(outcome.status === 'canceled' ? 130 : 1);
+          }
+          process.exit(0);
+        } catch (err) {
+          // CRITICAL: this catch MUST NOT include the phrase, the
+          // mnemonic, or any user secret in the message. The pair flow
+          // does not produce phrase material, so this is structurally
+          // safe — but defense-in-depth: emit a fixed error string.
+          opts.logger.error(
+            `pair-only delegation crashed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.stderr.write('--pair-only failed (see logs).\n');
+          process.exit(2);
+        }
+      }
+
       if (cliOpts.nonInteractive) {
         // Non-interactive path — no readline, no prompts.
         const mode: 'generate' | 'restore' | null =
@@ -744,10 +849,18 @@ export function registerOnboardingCli(
         });
 
         if (cliOpts.json) {
+          // 3.3.1-rc.18 (issue #95) — emit deprecation on stderr when
+          // the JSON payload is about to include the plaintext phrase.
+          // stderr is intentional: stdout must remain a single
+          // machine-parseable JSON line.
+          if (cliOpts.emitPhrase && result.ok && result.mnemonic) {
+            process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
+          }
           process.stdout.write(JSON.stringify(result) + '\n');
         } else {
           if (result.ok) {
             if (result.mnemonic) {
+              process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
               process.stderr.write(
                 'WARNING: --emit-phrase was set. The plaintext recovery phrase was returned.\n' +
                   'For agent-driven flows, prefer reading ~/.totalreclaw/credentials.json directly ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.18",
+  "version": "3.3.1-rc.19",
   "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": [
@@ -54,7 +54,7 @@
     "skill.json"
   ],
   "scripts": {
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },

package/pair-cli.ts

@@ -92,8 +92,15 @@ export interface PairCliOutcome {
  *     gap) and must shell out to the CLI. Guarantees zero phrase material
  *     on stdout by construction — pair-crypto is x25519-only and the slim
  *     payload carries nothing BIP-39-adjacent.
+ *   - 'pair-only': (3.3.1-rc.18, issue #95) the same surface as 'url-pin',
+ *     but the URL field is named `pair_url` (matching the spec wording
+ *     for `openclaw totalreclaw onboard --pair-only`). Used by the
+ *     onboard CLI's `--pair-only` flag to provide a phrase-safe
+ *     alternative to the interactive phrase-print path. Emits ONLY
+ *     `{ v, pair_url, pin, expires_at_ms }`. Same zero-phrase invariant
+ *     as 'url-pin' — the underlying pair flow does no BIP-39 work.
  */
-export type PairCliOutputMode = 'human' | 'json' | 'url-pin';
+export type PairCliOutputMode = 'human' | 'json' | 'url-pin' | 'pair-only';
 
 /**
  * JSON payload emitted by runPairCli when outputMode === 'json'. Printed
@@ -121,6 +128,20 @@ export interface PairCliUrlPinPayload {
   expires_at_ms: number;
 }
 
+/**
+ * Slim payload for outputMode === 'pair-only'. Same shape as
+ * `PairCliUrlPinPayload` but with `pair_url` instead of `url` — the
+ * key name matches the spec for `onboard --pair-only` (issue #95).
+ * Phrase invariant: zero BIP-39 material on stdout by construction
+ * (the pair flow is x25519-only).
+ */
+export interface PairCliPairOnlyPayload {
+  v: 1;
+  pair_url: string;
+  pin: string;
+  expires_at_ms: number;
+}
+
 // ---------------------------------------------------------------------------
 // Default stdout IO
 // ---------------------------------------------------------------------------
@@ -232,10 +253,12 @@ export async function runPairCli(
   }
 
   // 2. Build the URL unconditionally, but only render the QR for modes
-  //    that actually emit it. url-pin mode skips the renderer entirely —
-  //    no CPU cost, no qrcode-terminal import, no ASCII on stdout.
+  //    that actually emit it. url-pin and pair-only modes skip the
+  //    renderer entirely — no CPU cost, no qrcode-terminal import, no
+  //    ASCII on stdout.
   const url = deps.renderPairingUrl(session);
-  const qrAscii = outputMode === 'url-pin' ? '' : await new Promise<string>((resolve) => {
+  const skipsQr = outputMode === 'url-pin' || outputMode === 'pair-only';
+  const qrAscii = skipsQr ? '' : await new Promise<string>((resolve) => {
     // Guard against QR renderers that never fire their callback (shouldn't
     // happen with qrcode-terminal, but defensive): a 10-second timeout
     // returns an empty string so we never hang the pairing flow.
@@ -261,7 +284,8 @@ export async function runPairCli(
     }
   });
 
-  // 3. Emit the visible surface (JSON/url-pin first — single line — or human copy).
+  // 3. Emit the visible surface (JSON/url-pin/pair-only first — single
+  //    line — or human copy).
   if (outputMode === 'url-pin') {
     const payload: PairCliUrlPinPayload = {
       v: 1,
@@ -270,6 +294,14 @@ export async function runPairCli(
       expires_at_ms: session.expiresAtMs,
     };
     stdout.write(JSON.stringify(payload) + '\n');
+  } else if (outputMode === 'pair-only') {
+    const payload: PairCliPairOnlyPayload = {
+      v: 1,
+      pair_url: url,
+      pin: session.secondaryCode,
+      expires_at_ms: session.expiresAtMs,
+    };
+    stdout.write(JSON.stringify(payload) + '\n');
   } else if (outputMode === 'json') {
     const payload: PairCliJsonPayload = {
       v: 1,
@@ -304,9 +336,10 @@ export async function runPairCli(
     canceled = true;
   });
 
-  // 5. Poll — status transitions only surface in human mode; json/url-pin
-  //    modes stay silent after the single payload line so agents parsing
-  //    stdout get one JSON line and an exit code, nothing else.
+  // 5. Poll — status transitions only surface in human mode; json /
+  //    url-pin / pair-only modes stay silent after the single payload
+  //    line so agents parsing stdout get one JSON line and an exit
+  //    code, nothing else.
   const emitStatus = (text: string): void => {
     if (outputMode === 'human') stdout.write(text);
   };