@totalreclaw/totalreclaw 3.3.12 → 3.3.13

package/{llm-client.ts → llm/llm-client.ts}

@@ -9,7 +9,7 @@
  * @huggingface/transformers). No API key needed for embeddings.
  */
 
-import { CONFIG } from './config.js';
+import { CONFIG } from '../config.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -991,4 +991,4 @@ export {
   configureEmbedder,
   // 3.3.3-rc.1 (#187): pre-pair bundle prefetch
   prefetchEmbedderBundle,
-} from './embedding.js';
+} from '../embedding/embedding.js';

package/{hot-cache-wrapper.ts → memory/hot-cache-wrapper.ts}

@@ -96,12 +96,12 @@ export class PluginHotCache {
     if (!fs.existsSync(this.cachePath)) return;
 
     try {
-      const data = fs.readFileSync(this.cachePath);
-      if (data.length < IV_LENGTH + TAG_LENGTH) return;
+      const encryptedFile = fs.readFileSync(this.cachePath);
+      if (encryptedFile.length < IV_LENGTH + TAG_LENGTH) return;
 
-      const iv = data.subarray(0, IV_LENGTH);
-      const tag = data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
-      const ciphertext = data.subarray(IV_LENGTH + TAG_LENGTH);
+      const iv = encryptedFile.subarray(0, IV_LENGTH);
+      const tag = encryptedFile.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+      const ciphertext = encryptedFile.subarray(IV_LENGTH + TAG_LENGTH);
 
       const decipher = crypto.createDecipheriv('aes-256-gcm', this.key, iv);
       decipher.setAuthTag(tag);

package/{memory-runtime.ts → memory/memory-runtime.ts}

@@ -65,7 +65,7 @@
 // (no OpenClaw type import) so the plugin compiles without depending on
 // OpenClaw's type package.
 // ---------------------------------------------------------------------------
-import { EXTRACTION_SYSTEM_PROMPT } from './extractor.js';
+import { EXTRACTION_SYSTEM_PROMPT } from '../extraction/extractor.js';
 
 // ---------------------------------------------------------------------------
 // Types — injected caller shapes. Kept loose (no OpenClaw type import) so

package/{pin.ts → memory/pin.ts}

@@ -16,17 +16,17 @@ import {
   mapTypeToCategory,
   readV1Blob,
   type PinStatus,
-} from './claims-helper.js';
+} from '../extraction/claims-helper.js';
 import {
   findLoserClaimInDecisionLog,
   maybeWriteFeedbackForPin,
   type ContradictionLogger,
-} from './contradiction-sync.js';
-import { isValidMemoryType, V0_TO_V1_TYPE } from './extractor.js';
-import type { MemoryType, MemorySource, MemoryScope, MemoryVolatility } from './extractor.js';
-import { PROTOBUF_VERSION_V4 } from './subgraph-store.js';
-import type { SubgraphSearchFact } from './subgraph-search.js';
-import { confirmIndexed, type ConfirmIndexedOptions } from './confirm-indexed.js';
+} from '../contradiction/contradiction-sync.js';
+import { isValidMemoryType, V0_TO_V1_TYPE } from '../extraction/extractor.js';
+import type { MemoryType, MemorySource, MemoryScope, MemoryVolatility } from '../extraction/extractor.js';
+import { PROTOBUF_VERSION_V4 } from '../subgraph/subgraph-store.js';
+import type { SubgraphSearchFact } from '../subgraph/subgraph-search.js';
+import { confirmIndexed, type ConfirmIndexedOptions } from '../subgraph/confirm-indexed.js';
 
 // Lazy-load WASM core (mirrors claims-helper.ts pattern — plays nicely under
 // both the OpenClaw runtime (CJS-ish tsx) and bare Node ESM used by tests).
@@ -151,9 +151,9 @@ export interface ParsedBlob {
 
 /** Parse a decrypted blob into a canonical mutable Claim + current human status. */
 export function parseBlobForPin(decrypted: string): ParsedBlob {
-  let obj: Record<string, unknown>;
+  let parsed: Record<string, unknown>;
   try {
-    obj = JSON.parse(decrypted) as Record<string, unknown>;
+    parsed = JSON.parse(decrypted) as Record<string, unknown>;
   } catch {
     const shortClaim = buildCanonicalObjectFromLegacy(decrypted, {});
     return {
@@ -167,16 +167,16 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
   // v1 payload (plugin v3.0.0+): long-form fields + schema_version "1.x".
   // Preserve the v1 structure so the pin path can emit v1 on output.
   if (
-    typeof obj.text === 'string' &&
-    typeof obj.type === 'string' &&
-    typeof obj.schema_version === 'string' &&
-    obj.schema_version.startsWith('1.')
+    typeof parsed.text === 'string' &&
+    typeof parsed.type === 'string' &&
+    typeof parsed.schema_version === 'string' &&
+    parsed.schema_version.startsWith('1.')
   ) {
     const v1 = readV1Blob(decrypted);
     if (v1) {
       // Current status = pinStatus if present, else active.
       const human: HumanStatus = v1.pinStatus === 'pinned' ? 'pinned' : 'active';
-      const shortProjection = v1ToShortKeyClaim(obj);
+      const shortProjection = v1ToShortKeyClaim(parsed);
       return {
         source: {
           kind: 'v1',
@@ -204,10 +204,10 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
   }
 
   // v0 canonical Claim — short keys present.
-  if (typeof obj.t === 'string' && typeof obj.c === 'string') {
-    const st = typeof obj.st === 'string' ? obj.st : 'a';
+  if (typeof parsed.t === 'string' && typeof parsed.c === 'string') {
+    const st = typeof parsed.st === 'string' ? parsed.st : 'a';
     const human = SHORT_TO_HUMAN[st] ?? 'active';
-    const cloned = JSON.parse(JSON.stringify(obj)) as Record<string, unknown>;
+    const cloned = JSON.parse(JSON.stringify(parsed)) as Record<string, unknown>;
     return {
       source: { kind: 'v0', claim: cloned },
       claim: cloned,
@@ -217,9 +217,9 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
   }
 
   // Legacy {text, metadata: {importance: 0-1}} shape.
-  if (typeof obj.text === 'string') {
-    const meta = (obj.metadata as Record<string, unknown>) ?? {};
-    const shortClaim = buildCanonicalObjectFromLegacy(obj.text, meta);
+  if (typeof parsed.text === 'string') {
+    const meta = (parsed.metadata as Record<string, unknown>) ?? {};
+    const shortClaim = buildCanonicalObjectFromLegacy(parsed.text, meta);
     return {
       source: { kind: 'v0', claim: shortClaim },
       claim: shortClaim,

package/{retype-setscope.ts → memory/retype-setscope.ts}

@@ -35,21 +35,21 @@ import {
   mapTypeToCategory,
   readV1Blob,
   type PinStatus,
-} from './claims-helper.js';
+} from '../extraction/claims-helper.js';
 import {
   isValidMemoryType,
   VALID_MEMORY_SCOPES,
   V0_TO_V1_TYPE,
-} from './extractor.js';
+} from '../extraction/extractor.js';
 import type {
   MemoryType,
   MemorySource,
   MemoryScope,
   MemoryVolatility,
-} from './extractor.js';
-import { PROTOBUF_VERSION_V4 } from './subgraph-store.js';
-import type { SubgraphSearchFact } from './subgraph-search.js';
-import { confirmIndexed, type ConfirmIndexedOptions } from './confirm-indexed.js';
+} from '../extraction/extractor.js';
+import { PROTOBUF_VERSION_V4 } from '../subgraph/subgraph-store.js';
+import type { SubgraphSearchFact } from '../subgraph/subgraph-search.js';
+import { confirmIndexed, type ConfirmIndexedOptions } from '../subgraph/confirm-indexed.js';
 
 // Lazy-load WASM core — mirrors pin.ts pattern.
 const requireWasm = createRequire(import.meta.url);
@@ -163,19 +163,19 @@ interface NormalizedFact {
 }
 
 function projectFromDecrypted(decrypted: string): NormalizedFact | null {
-  let obj: Record<string, unknown>;
+  let parsed: Record<string, unknown>;
   try {
-    obj = JSON.parse(decrypted) as Record<string, unknown>;
+    parsed = JSON.parse(decrypted) as Record<string, unknown>;
   } catch {
     return null;
   }
 
   // v1 blob (schema_version "1.x")
   if (
-    typeof obj.text === 'string' &&
-    typeof obj.type === 'string' &&
-    typeof obj.schema_version === 'string' &&
-    obj.schema_version.startsWith('1.')
+    typeof parsed.text === 'string' &&
+    typeof parsed.type === 'string' &&
+    typeof parsed.schema_version === 'string' &&
+    parsed.schema_version.startsWith('1.')
   ) {
     const v1 = readV1Blob(decrypted);
     if (v1) {
@@ -198,20 +198,20 @@ function projectFromDecrypted(decrypted: string): NormalizedFact | null {
   }
 
   // v0 short-key blob — upgrade to v1 shape.
-  if (typeof obj.t === 'string' && typeof obj.c === 'string') {
-    const v0Type = typeof obj.c === 'string' ? obj.c : 'fact';
+  if (typeof parsed.t === 'string' && typeof parsed.c === 'string') {
+    const v0Type = typeof parsed.c === 'string' ? parsed.c : 'fact';
     const v1Type: MemoryType = (V0_TO_V1_TYPE as Record<string, MemoryType>)[v0Type] ?? 'claim';
-    const imp = typeof obj.i === 'number' ? obj.i : 5;
-    const conf = typeof obj.cf === 'number' ? obj.cf : 0.85;
-    const sa = typeof obj.sa === 'string' ? obj.sa : 'user';
+    const imp = typeof parsed.i === 'number' ? parsed.i : 5;
+    const conf = typeof parsed.cf === 'number' ? parsed.cf : 0.85;
+    const sa = typeof parsed.sa === 'string' ? parsed.sa : 'user';
     const validSource: MemorySource = (
       ['user', 'user-inferred', 'assistant', 'external', 'derived'] as const
     ).includes(sa as MemorySource)
       ? (sa as MemorySource)
       : 'user';
-    const ea = typeof obj.ea === 'string' ? obj.ea : new Date().toISOString();
-    const entities = Array.isArray(obj.e)
-      ? (obj.e as unknown[])
+    const ea = typeof parsed.ea === 'string' ? parsed.ea : new Date().toISOString();
+    const entities = Array.isArray(parsed.e)
+      ? (parsed.e as unknown[])
           .map((e) => {
             if (!e || typeof e !== 'object') return null;
             const entity = e as Record<string, unknown>;
@@ -224,7 +224,7 @@ function projectFromDecrypted(decrypted: string): NormalizedFact | null {
           .filter((e): e is { name: string; type: string; role?: string } => e !== null)
       : undefined;
     return {
-      text: typeof obj.t === 'string' ? obj.t : '',
+      text: typeof parsed.t === 'string' ? parsed.t : '',
       type: v1Type,
       source: validSource,
       scope: undefined,

package/{tool-gating.ts → memory/tool-gating.ts}

@@ -30,7 +30,7 @@
  * `resolveOnboardingState` already does; no network; no env reads.
  */
 
-import type { OnboardingState } from './fs-helpers.js';
+import type { OnboardingState } from '../fs-helpers.js';
 
 /**
  * Tool names gated on `state=active`. These are the bundled NATIVE memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.12",
+  "version": "3.3.13",
   "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": [
@@ -34,8 +34,6 @@
     "@scure/bip39": "^2.2.0",
     "@totalreclaw/client": "^1.3.0",
     "@totalreclaw/core": "^2.5.3",
-    "@types/qrcode": "^1.5.6",
-    "@types/ws": "^8.5.12",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.3"
@@ -43,17 +41,19 @@
   "//": "@huggingface/transformers + onnxruntime-node deliberately omitted from runtime deps. They are heavy native bundles (~700 MB peak install RAM) that OOM-killed the OpenClaw gateway on small VPS during `openclaw plugins install` in rc.21 (issue: 3.7 GB Hetzner host). rc.22 ships them via a lazy GitHub-Releases bundle (`embedder-v1.tar.gz`) downloaded on first call to embed(). See `embedder-network.ts` + `scripts/build-embedder-bundle.mjs`. The dev-deps below are for type-checking + bundle generation only; npm install of the plugin tarball never installs them.",
   "devDependencies": {
     "@huggingface/transformers": "^4.0.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.5.12",
     "onnxruntime-node": "^1.24.0",
     "typescript": "^5.5.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "tr": "./dist/tr-cli.js"
+    "tr": "./dist/cli/tr-cli.js"
   },
   "files": [
     "dist/",
-    "*.ts",
+    "**/*.ts",
     "import-adapters/",
     "!**/*.test.ts",
     "!pocv2-e2e-test.ts",
@@ -68,7 +68,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx batch-gate.test.ts && npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx llm-client-json-mode.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 pair-http.test.ts && npx tsx pair-http-route-registration.test.ts && npx tsx pair-http-init.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx initcode-lifecycle.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 && npx tsx import-state.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx skill-register.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-native.test.ts &&npx tsx tr-cli-json-output.test.ts && npx tsx import-upgrade-cli.test.ts && npx tsx cli-registercli-scope.test.ts && npx tsx postinstall-validate.test.ts && npx tsx credential-provider.test.ts && npx tsx memory-runtime.test.ts && npx tsx tools.test.ts && npx tsx register-native.test.ts && npx tsx relay.test.ts && npx tsx vault-crypto.test.ts && npx tsx entry-env.test.ts && npx tsx trajectory-poller.test.ts && npx tsx billing-cache.test.ts && npx tsx dataedge-write-target.test.ts",
+    "test": "node run-tests.mjs",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "check-version-drift": "node ../scripts/check-version-drift.mjs",

package/{credential-provider.ts → pairing/credential-provider.ts}

@@ -36,13 +36,13 @@
 
 import fs from 'node:fs';
 
-import { CONFIG } from './config.js';
+import { CONFIG } from '../config.js';
 import {
   loadCredentialsJson,
   writeCredentialsJson,
   deleteCredentialsFile,
   type CredentialsFile,
-} from './fs-helpers.js';
+} from '../fs-helpers.js';
 
 /**
  * Provider interface — three methods cover the lifecycle:

package/{first-run.ts → pairing/first-run.ts}

@@ -37,7 +37,7 @@
  *     crypto code for a copy change.
  */
 
-import { loadCredentialsJson, extractBootstrapMnemonic } from './fs-helpers.js';
+import { loadCredentialsJson, extractBootstrapMnemonic } from '../fs-helpers.js';
 
 // ---------------------------------------------------------------------------
 // Canonical copy — single source of truth for the welcome-on-first-run UX.

package/{onboarding-cli.ts → pairing/onboarding-cli.ts}

@@ -52,7 +52,7 @@ import {
   writeOnboardingState,
   loadOnboardingState,
   type OnboardingState,
-} from './fs-helpers.js';
+} from '../fs-helpers.js';
 
 // ---------------------------------------------------------------------------
 // User-facing strings (centralised so tests can assert on them + localisation
@@ -665,15 +665,15 @@ export async function runNonInteractiveOnboard(
     }
   }
 
-  const result: NonInteractiveOnboardResult = {
+  const onboardResult: NonInteractiveOnboardResult = {
     ok: true,
     action,
     credentials_path: inputs.credentialsPath,
   };
-  if (scopeAddress) result.scope_address = scopeAddress;
-  if (inputs.emitPhrase) result.mnemonic = mnemonic;
+  if (scopeAddress) onboardResult.scope_address = scopeAddress;
+  if (inputs.emitPhrase) onboardResult.mnemonic = mnemonic;
   void state; // Touch for clarity — state is persisted via writeCredsAndState.
-  return result;
+  return onboardResult;
 }
 
 // ---------------------------------------------------------------------------
@@ -840,7 +840,7 @@ export function registerOnboardingCli(
           phrase = await readAllStdin();
         }
 
-        const result = await runNonInteractiveOnboard({
+        const onboardResult = await runNonInteractiveOnboard({
           credentialsPath: opts.credentialsPath,
           statePath: opts.statePath,
           mode,
@@ -854,13 +854,13 @@ export function registerOnboardingCli(
           // 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) {
+          if (cliOpts.emitPhrase && onboardResult.ok && onboardResult.mnemonic) {
             process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
           }
-          process.stdout.write(JSON.stringify(result) + '\n');
+          process.stdout.write(JSON.stringify(onboardResult) + '\n');
         } else {
-          if (result.ok) {
-            if (result.mnemonic) {
+          if (onboardResult.ok) {
+            if (onboardResult.mnemonic) {
               process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
               process.stderr.write(
                 'WARNING: --emit-phrase was set. The plaintext recovery phrase was returned.\n' +
@@ -869,15 +869,15 @@ export function registerOnboardingCli(
               );
             }
             process.stdout.write(
-              `onboarding: ok  action=${result.action}  ` +
-                (result.scope_address ? `scope_address=${result.scope_address}  ` : '') +
-                `credentials=${result.credentials_path}\n`,
+              `onboarding: ok  action=${onboardResult.action}  ` +
+                (onboardResult.scope_address ? `scope_address=${onboardResult.scope_address}  ` : '') +
+                `credentials=${onboardResult.credentials_path}\n`,
             );
           } else {
-            process.stderr.write(`onboarding: ${result.error}: ${result.error_detail ?? ''}\n`);
+            process.stderr.write(`onboarding: ${onboardResult.error}: ${onboardResult.error_detail ?? ''}\n`);
           }
         }
-        process.exit(result.ok ? 0 : 1);
+        process.exit(onboardResult.ok ? 0 : 1);
       }
 
       if (cliOpts.json) {
@@ -890,18 +890,18 @@ export function registerOnboardingCli(
       // Interactive path — original 3.2.0 behaviour preserved in full.
       const io = buildDefaultIo();
       try {
-        const result = await runOnboardingWizard({
+        const wizardResult = await runOnboardingWizard({
           credentialsPath: opts.credentialsPath,
           statePath: opts.statePath,
           io,
         });
-        if (result.error) {
-          opts.logger.warn(`onboarding wizard exited with error: ${result.error}`);
+        if (wizardResult.error) {
+          opts.logger.warn(`onboarding wizard exited with error: ${wizardResult.error}`);
           io.close();
           process.exit(1);
         }
-        if (result.choice === 'generate' || result.choice === 'import') {
-          opts.logger.info(`onboarding: state=active createdBy=${result.state?.createdBy}`);
+        if (wizardResult.choice === 'generate' || wizardResult.choice === 'import') {
+          opts.logger.info(`onboarding: state=active createdBy=${wizardResult.state?.createdBy}`);
         }
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/{pair-cli-relay.ts → pairing/pair-cli-relay.ts}

@@ -51,15 +51,15 @@ import {
   loadCredentialsJson,
   writeCredentialsJson,
   writeOnboardingState,
-} from './fs-helpers.js';
+} from '../fs-helpers.js';
 import {
   awaitPhraseUpload,
   openRemotePairSession,
 } from './pair-remote-client.js';
-import { setRecoveryPhraseOverride } from './config.js';
+import { setRecoveryPhraseOverride } from '../config.js';
 import { encodePng, encodeUnicode } from './pair-qr.js';
-import { deriveKeys, computeAuthKeyHash } from './crypto.js';
-import { createApiClient } from './api-client.js';
+import { deriveKeys, computeAuthKeyHash } from '../crypto/crypto.js';
+import { createApiClient } from '../billing/api-client.js';
 import type {
   PairCliIo,
   PairCliJsonPayload,
@@ -270,7 +270,7 @@ export async function runRelayPairCli(
   };
 
   try {
-    const result = await awaitPhraseUpload(session, {
+    const completion = await awaitPhraseUpload(session, {
       phraseValidator: (p: string) => validateMnemonic(p, wordlist),
       completePairing: async ({ mnemonic }) => {
         try {
@@ -296,8 +296,8 @@ export async function runRelayPairCli(
             // serves both protocols on the same host.
             const httpsBase = opts.relayBaseUrl.replace(/^ws/, 'http').replace(/\/+$/, '');
             const apiClient = createApiClient(httpsBase);
-            const result = await apiClient.register(authKeyHash, saltHex);
-            registeredUserId = result.user_id;
+            const registerResult = await apiClient.register(authKeyHash, saltHex);
+            registeredUserId = registerResult.user_id;
             opts.logger.info(
               `pair-cli (relay): registered user_id=${registeredUserId} (salt + auth-key persisted)`,
             );
@@ -361,12 +361,12 @@ export async function runRelayPairCli(
       emitStatus('\nCanceled. Pairing session invalidated.\n');
       return { status: 'canceled', sid: session.token };
     }
-    if (result.state === 'active') {
+    if (completion.state === 'active') {
       emitStatus('\nPairing complete. Account is active.\n');
       return { status: 'completed', sid: session.token };
     }
-    emitStatus(`\nPairing failed: ${result.error ?? 'unknown_error'}\n`);
-    return { status: 'error', sid: session.token, error: result.error ?? 'unknown_error' };
+    emitStatus(`\nPairing failed: ${completion.error ?? 'unknown_error'}\n`);
+    return { status: 'error', sid: session.token, error: completion.error ?? 'unknown_error' };
   } catch (err) {
     if (canceled) {
       emitStatus('\nCanceled. Pairing session invalidated.\n');

package/{pair-crypto.ts → pairing/pair-crypto.ts}

@@ -39,4 +39,4 @@ export {
   aeadEncryptWithSessionKey,
   encryptPairingPayload,
   compareSecondaryCodesCT,
-} from './vault-crypto.js';
+} from '../crypto/vault-crypto.js';

package/{pair-http.ts → pairing/pair-http.ts}

@@ -542,7 +542,7 @@ export function buildPairRoutes(cfg: PairHttpConfig): PairRouteBundle {
     //    sid/mode for log correlation.
     void (async (): Promise<void> => {
       try {
-        const result = await awaitPhraseUpload(session, {
+        const completion = await awaitPhraseUpload(session, {
           phraseValidator: validate,
           timeoutMs: cfg.initAwaitTimeoutMs,
           completePairing: async ({ mnemonic }) => {
@@ -557,13 +557,13 @@ export function buildPairRoutes(cfg: PairHttpConfig): PairRouteBundle {
             return cfg.completePairing({ mnemonic, session: sessionLike });
           },
         });
-        if (result.state === 'active') {
+        if (completion.state === 'active') {
           cfg.logger.info(
             `pair-http /init: session ${redactSid(session.token)} completed in-process; onboarding active`,
           );
         } else {
           cfg.logger.warn(
-            `pair-http /init: session ${redactSid(session.token)} completion non-active: ${result.error ?? 'unknown'}`,
+            `pair-http /init: session ${redactSid(session.token)} completion non-active: ${completion.error ?? 'unknown'}`,
           );
         }
       } catch (err) {

package/{pair-remote-client.ts → pairing/pair-remote-client.ts}

@@ -259,9 +259,9 @@ export async function openRemotePairSession(
   try {
     const text = typeof raw === 'string' ? raw : Buffer.from(raw as ArrayBuffer).toString('utf-8');
     msg = JSON.parse(text);
-  } catch {
+  } catch (err) {
     safeClose(ws);
-    throw new Error('pair-remote-client: opened frame not valid JSON');
+    throw new Error('pair-remote-client: opened frame not valid JSON', { cause: err });
   }
 
   if (msg.type === 'error') {
@@ -331,10 +331,10 @@ export async function awaitPhraseUpload(
   try {
     const text = typeof raw === 'string' ? raw : Buffer.from(raw as ArrayBuffer).toString('utf-8');
     msg = JSON.parse(text);
-  } catch {
+  } catch (err) {
     safeSend(ws, { type: 'nack', error: 'bad_json' });
     safeClose(ws);
-    throw new Error('pair-remote-client: forward frame not valid JSON');
+    throw new Error('pair-remote-client: forward frame not valid JSON', { cause: err });
   }
 
   if (msg.type !== 'forward') {
@@ -395,9 +395,9 @@ export async function awaitPhraseUpload(
 
   // Hand off to the caller-supplied completion handler. Wrapped in try/finally
   // so we always drop our own reference to the mnemonic.
-  let result: RelayCompletionResult;
+  let completion: RelayCompletionResult;
   try {
-    result = await opts.completePairing({ mnemonic, session });
+    completion = await opts.completePairing({ mnemonic, session });
   } catch (err) {
     safeSend(ws, { type: 'nack', error: 'completion_failed' });
     safeClose(ws);
@@ -408,15 +408,15 @@ export async function awaitPhraseUpload(
     mnemonic = '';
   }
 
-  if (result.state !== 'active') {
-    safeSend(ws, { type: 'nack', error: result.error ?? 'completion_failed' });
+  if (completion.state !== 'active') {
+    safeSend(ws, { type: 'nack', error: completion.error ?? 'completion_failed' });
     safeClose(ws);
-    return result;
+    return completion;
   }
 
   safeSend(ws, { type: 'ack' });
   safeClose(ws);
-  return result;
+  return completion;
 }
 
 /**

package/{pair-session-store.ts → pairing/pair-session-store.ts}

@@ -592,16 +592,16 @@ export async function updatePairSession(
     }
     const current = pruned.file.sessions[idx];
     const next = mutate(current);
-    let result: PairSession | null;
+    let mutatedSession: PairSession | null;
     if (next === null) {
       pruned.file.sessions.splice(idx, 1);
-      result = null;
+      mutatedSession = null;
     } else {
       pruned.file.sessions[idx] = next;
-      result = next;
+      mutatedSession = next;
     }
     writePairSessionsFileSync(sessionsPath, pruned.file);
-    return result;
+    return mutatedSession;
   } finally {
     release();
   }

package/runtime/config-schema.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Plugin configSchema — static JSON-schema for the OpenClaw plugin config.
+// Extracted from index.ts; pure data, no runtime state.
+// ---------------------------------------------------------------------------
+
+export const CONFIG_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    publicUrl: {
+      type: 'string',
+      description:
+        "Public gateway URL for QR pairing (e.g. 'https://gateway.example.com:18789'). Overrides the auto-resolution cascade in buildPairingUrl.",
+    },
+    extraction: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        enabled: {
+          type: 'boolean',
+          description: 'Enable/disable auto-extraction (default: true)',
+        },
+        model: {
+          type: 'string',
+          description:
+            "Shorthand: override just the extraction model (e.g., 'glm-4.5-flash', 'gpt-4.1-mini'). For a full provider override use extraction.llm.",
+        },
+        interval: {
+          type: 'number',
+          description: 'Number of turns between automatic extractions (default: 3)',
+        },
+        maxFactsPerExtraction: {
+          type: 'number',
+          description: 'Hard cap on facts extracted per turn (default: 15)',
+        },
+        llm: {
+          type: 'object',
+          additionalProperties: false,
+          description:
+            'Explicit LLM override block. Highest-priority tier in the extraction-provider cascade. Any subset of provider+apiKey is enough to pin a provider.',
+          properties: {
+            provider: {
+              type: 'string',
+              description:
+                "Provider name: zai | openai | anthropic | gemini | google | mistral | groq | deepseek | openrouter | xai | together | cerebras.",
+            },
+            model: {
+              type: 'string',
+              description: 'Explicit model id. If omitted, deriveCheapModel(provider) picks a sensible default.',
+            },
+            apiKey: {
+              type: 'string',
+              description: 'API key for the selected provider. Required for the override to take effect.',
+            },
+            baseUrl: {
+              type: 'string',
+              description: 'Override the provider base URL (self-hosted / custom gateway setups).',
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;