@totalreclaw/totalreclaw 3.3.1-rc.2 → 3.3.1-rc.21

package/dist/gateway-url.js

@@ -0,0 +1,197 @@
+/**
+ * gateway-url — autodetect the gateway's externally-reachable URL for QR
+ * pairing. This module runs sync + network-I/O-free so the OpenClaw
+ * dangerous-code scanner never flags it (the 3.3.1-rc.1 implementation
+ * used `child-process.execFileSync('tailscale', ...)` which blocked every
+ * `openclaw plugins install` — see QA report
+ * `docs/notes/QA-plugin-3.3.1-rc.1-20260422-0121.md`).
+ *
+ * Two layers:
+ *
+ *   1. Tailscale — PASSIVE detection via `os.networkInterfaces()`. If a
+ *      `tailscale*` NIC has a CGNAT IPv4 (100.64/10), we return that IP
+ *      as an auto-detected host — the operator can verify + override via
+ *      `plugins.entries.totalreclaw.config.publicUrl` when they want a
+ *      proper MagicDNS hostname. We DO NOT call `tailscale` the CLI —
+ *      that requires `child-process` which the scanner blocks.
+ *
+ *   2. LAN — first non-loopback, non-virtual IPv4 interface. Emit with a
+ *      caveat that the URL only works on the same network.
+ *
+ *   3. Null — no signal; caller falls through to localhost with a warning.
+ *
+ * The caller is expected to surface `detected.note` to the operator and
+ * tell them to set `publicUrl` when auto-detect isn't good enough
+ * (remote-accessible https, MagicDNS, etc.).
+ *
+ * Scope and scanner surface
+ * -------------------------
+ * - No `child-process` import — the original scanner-blocking flaw.
+ * - No `fetch` / `post` / `http.request` substrings — the potential-
+ *   exfiltration rule is also clear.
+ * - Only `node:os` (synchronous, local) is used; no disk reads, no
+ *   subprocess execution, no network calls.
+ */
+import os from 'node:os';
+// ---------------------------------------------------------------------------
+// Tailscale — passive detection (no subprocess, no network I/O)
+// ---------------------------------------------------------------------------
+/** CGNAT range 100.64.0.0/10 — Tailscale assigns IPs here by default. */
+function isTailscaleCGNAT(addr) {
+    if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(addr))
+        return false;
+    const parts = addr.split('.').map((p) => Number.parseInt(p, 10));
+    if (parts[0] !== 100)
+        return false;
+    return parts[1] >= 64 && parts[1] <= 127;
+}
+/**
+ * Passive Tailscale detection — checks `os.networkInterfaces()` for a
+ * `tailscale*` NIC carrying a CGNAT IPv4. Returns null if not found.
+ *
+ * Unlike rc.1, this does NOT shell out to `tailscale status` — that
+ * tripped the OpenClaw scanner's dangerous-code detector and blocked
+ * install. The trade-off: we surface the raw CGNAT IP instead of the
+ * MagicDNS hostname. Operators who want a MagicDNS host must set
+ * `plugins.entries.totalreclaw.config.publicUrl` explicitly (documented
+ * in SKILL.md).
+ */
+export function detectTailscaleHost(options) {
+    const nif = (options?.networkInterfaces ?? os.networkInterfaces)();
+    for (const [name, addrs] of Object.entries(nif)) {
+        if (!name.toLowerCase().startsWith('tailscale'))
+            continue;
+        if (!addrs)
+            continue;
+        for (const a of addrs) {
+            if (a.family !== 'IPv4' || a.internal)
+                continue;
+            if (isTailscaleCGNAT(a.address)) {
+                return {
+                    kind: 'tailscale',
+                    host: a.address,
+                    tls: false,
+                    note: `Tailscale CGNAT IP detected on interface ${name}. For a proper ` +
+                        `https://<magicdns>.ts.net URL, set plugins.entries.totalreclaw.config.publicUrl ` +
+                        `(Tailscale CLI auto-resolution was removed in 3.3.1-rc.2 to pass the ` +
+                        `OpenClaw security scanner).`,
+                };
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// LAN autodetect
+// ---------------------------------------------------------------------------
+/** Interfaces we explicitly skip — these are virtual / tunneled. */
+const SKIP_IFACE_PREFIXES = [
+    'lo',
+    'tailscale',
+    'docker',
+    'br-',
+    'bridge',
+    'veth',
+    'utun',
+    'vmnet',
+    'ovpn',
+    'wg',
+    'virbr',
+    'tun',
+    'ham',
+];
+function shouldSkipIface(name) {
+    const lower = name.toLowerCase();
+    return SKIP_IFACE_PREFIXES.some((p) => lower.startsWith(p));
+}
+/**
+ * Docker container internal IP detection — issue #110 fix 4.
+ *
+ * From INSIDE a Docker container, `eth0` carries the container's bridge IP
+ * (e.g. `172.18.0.2`). That IP is reachable from other containers on the
+ * SAME Docker network but NOT from the host browser, the user's phone, or
+ * any external device. Surfacing it as the pairing URL produces a hard-
+ * dead user experience: "scan QR" yields connection-refused.
+ *
+ * Docker default-bridge ranges:
+ *   - 172.17.0.0/16 — `bridge` (default)
+ *   - 172.18.0.0/16 .. 172.31.0.0/16 — user-defined networks
+ *
+ * We use the conservative test: 172.16.0.0/12 (the full RFC-1918 172.x
+ * range, which is what Docker draws from). If the host is clearly Docker
+ * (`/.dockerenv`), we treat 172.16-31.x.x AS Docker-internal and skip it.
+ *
+ * Outside Docker, 172.16.x.x can be a legitimate corporate LAN, so we
+ * only apply the rule when we have positive Docker evidence.
+ */
+export function isDockerInternalIp(addr) {
+    if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(addr))
+        return false;
+    const parts = addr.split('.').map((p) => Number.parseInt(p, 10));
+    if (parts[0] !== 172)
+        return false;
+    return parts[1] >= 16 && parts[1] <= 31;
+}
+/**
+ * Pick the first non-loopback, non-virtual IPv4 address. Returns null if
+ * none found (headless VPS with only lo + tailscale, for example).
+ *
+ * issue #110 fix 4: when the host is detected as Docker (caller passes
+ * `isDocker: true`), skip Docker-bridge IPs in the 172.16/12 range — they
+ * are container-internal and useless for any external browser. Returning
+ * null from this function in that scenario lets `buildPairingUrl` fall
+ * through to the localhost-with-relay-fallback warning rather than handing
+ * the user a dead URL.
+ */
+export function detectLanHost(options) {
+    const nif = (options?.networkInterfaces ?? os.networkInterfaces)();
+    for (const [name, addrs] of Object.entries(nif)) {
+        if (shouldSkipIface(name))
+            continue;
+        if (!addrs)
+            continue;
+        for (const a of addrs) {
+            if (a.family !== 'IPv4' || a.internal)
+                continue;
+            // issue #110 fix 4 — Docker container internal IP is unreachable
+            // from any external browser. Skip it so the caller falls back to
+            // the relay-brokered URL.
+            if (options?.isDocker && isDockerInternalIp(a.address))
+                continue;
+            return {
+                kind: 'lan',
+                host: a.address,
+                tls: false,
+                note: `LAN IPv4 on interface ${name} — only reachable from the same network.`,
+            };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Composed resolver
+// ---------------------------------------------------------------------------
+/**
+ * Try Tailscale first (passive NIC probe), then LAN. Returns null when
+ * neither is available (caller falls through to localhost).
+ *
+ * Sync: no I/O, no subprocess, no network. Safe in sync callers like
+ * `buildPairingUrl` in index.ts.
+ *
+ * issue #110 fix 4: the `isDocker` option, when true, skips the 172.16/12
+ * Docker-bridge range during LAN detection. The caller (index.ts) passes
+ * `isRunningInDocker()` so we don't surface a container-internal IP that
+ * no external browser can reach.
+ */
+export function detectGatewayHost(options) {
+    const ts = detectTailscaleHost({ networkInterfaces: options?.networkInterfaces });
+    if (ts)
+        return ts;
+    const lan = detectLanHost({
+        networkInterfaces: options?.networkInterfaces,
+        isDocker: options?.isDocker,
+    });
+    if (lan)
+        return lan;
+    return null;
+}

package/dist/generate-mnemonic.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env npx tsx
+/**
+ * Generate a BIP-39 12-word mnemonic for use as TOTALRECLAW_RECOVERY_PHRASE.
+ *
+ * Usage: npx tsx generate-mnemonic.ts
+ */
+import { generateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+const mnemonic = generateMnemonic(wordlist, 128);
+console.log('\n  Your TotalReclaw recovery phrase (12 words):\n');
+console.log(`  ${mnemonic}\n`);
+console.log('  WRITE THIS DOWN. If you lose it, your memories are unrecoverable.');
+console.log('  Set it as TOTALRECLAW_RECOVERY_PHRASE in your .env file.\n');

package/dist/hot-cache-wrapper.js

@@ -0,0 +1,101 @@
+/**
+ * Hot cache wrapper for the plugin.
+ *
+ * Self-contained XChaCha20-Poly1305 encrypted cache (same implementation as
+ * client/src/cache/hot-cache.ts but without cross-package import).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_HOT_FACTS = 30;
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+export class PluginHotCache {
+    cachePath;
+    hotFacts = [];
+    factCount = 0;
+    lastSyncedBlock = 0;
+    smartAccountAddress = '';
+    lastUpdatedAt = 0;
+    lastQueryEmbedding = null;
+    key;
+    constructor(cachePath, hexKey) {
+        this.cachePath = cachePath;
+        this.key = Buffer.from(hexKey, 'hex');
+    }
+    getHotFacts() { return [...this.hotFacts]; }
+    getFactCount() { return this.factCount; }
+    getLastSyncedBlock() { return this.lastSyncedBlock; }
+    getSmartAccountAddress() { return this.smartAccountAddress; }
+    getLastUpdatedAt() { return this.lastUpdatedAt; }
+    getLastQueryEmbedding() { return this.lastQueryEmbedding ? [...this.lastQueryEmbedding] : null; }
+    setHotFacts(facts) {
+        const sorted = [...facts].sort((a, b) => b.importance - a.importance);
+        this.hotFacts = sorted.slice(0, MAX_HOT_FACTS);
+        this.lastUpdatedAt = Date.now();
+    }
+    setFactCount(count) { this.factCount = count; }
+    setLastSyncedBlock(block) { this.lastSyncedBlock = block; }
+    setSmartAccountAddress(addr) { this.smartAccountAddress = addr; }
+    setLastUpdatedAt(ts) { this.lastUpdatedAt = ts; }
+    setLastQueryEmbedding(embedding) { this.lastQueryEmbedding = embedding ? [...embedding] : null; }
+    /**
+     * Check if the cache is fresh (within TTL).
+     * @param ttlMs TTL in milliseconds (default: 5 minutes)
+     */
+    isFresh(ttlMs = 300_000) {
+        if (this.lastUpdatedAt === 0)
+            return false;
+        return (Date.now() - this.lastUpdatedAt) < ttlMs;
+    }
+    flush() {
+        const payload = {
+            hotFacts: this.hotFacts,
+            factCount: this.factCount,
+            lastSyncedBlock: this.lastSyncedBlock,
+            smartAccountAddress: this.smartAccountAddress,
+            lastUpdatedAt: this.lastUpdatedAt,
+            lastQueryEmbedding: this.lastQueryEmbedding,
+        };
+        const plaintext = Buffer.from(JSON.stringify(payload), 'utf-8');
+        const iv = crypto.randomBytes(IV_LENGTH);
+        const cipher = crypto.createCipheriv('aes-256-gcm', this.key, iv);
+        const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const output = Buffer.concat([iv, tag, encrypted]);
+        const dir = path.dirname(this.cachePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(this.cachePath, output);
+    }
+    load() {
+        if (!fs.existsSync(this.cachePath))
+            return;
+        try {
+            const data = fs.readFileSync(this.cachePath);
+            if (data.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 decipher = crypto.createDecipheriv('aes-256-gcm', this.key, iv);
+            decipher.setAuthTag(tag);
+            const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+            const payload = JSON.parse(decrypted.toString('utf-8'));
+            this.hotFacts = payload.hotFacts || [];
+            this.factCount = payload.factCount || 0;
+            this.lastSyncedBlock = payload.lastSyncedBlock || 0;
+            this.smartAccountAddress = payload.smartAccountAddress || '';
+            this.lastUpdatedAt = payload.lastUpdatedAt || 0;
+            this.lastQueryEmbedding = payload.lastQueryEmbedding || null;
+        }
+        catch {
+            this.hotFacts = [];
+            this.factCount = 0;
+            this.lastSyncedBlock = 0;
+            this.smartAccountAddress = '';
+            this.lastUpdatedAt = 0;
+            this.lastQueryEmbedding = null;
+        }
+    }
+}

package/dist/import-adapters/base-adapter.js

@@ -0,0 +1,64 @@
+/**
+ * Abstract base class for import adapters.
+ *
+ * Adapters are PARSERS only — they convert raw export data into either:
+ * - Pre-structured facts (Mem0, MCP Memory — facts are already atomic)
+ * - Conversation chunks (ChatGPT, Claude — need LLM extraction)
+ *
+ * The caller (import tool) handles LLM extraction, encryption, and storage.
+ */
+export class BaseImportAdapter {
+    /**
+     * Validate and clean a single fact.
+     * Returns null if the fact should be skipped.
+     */
+    validateFact(fact) {
+        // Text is required and must be non-empty
+        if (!fact.text || typeof fact.text !== 'string' || fact.text.trim().length < 3) {
+            return null;
+        }
+        // Truncate to 512 chars
+        const text = fact.text.trim().slice(0, 512);
+        // Normalize type
+        const validTypes = ['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'];
+        const type = validTypes.includes(fact.type)
+            ? fact.type
+            : 'fact';
+        // Normalize importance to 1-10
+        let importance = fact.importance ?? 5;
+        if (importance < 0 || importance > 1) {
+            // Already on 1-10 scale
+            importance = Math.max(1, Math.min(10, Math.round(importance)));
+        }
+        else {
+            // 0-1 scale — convert to 1-10
+            importance = Math.max(1, Math.round(importance * 10));
+        }
+        return {
+            text,
+            type,
+            importance,
+            source: fact.source ?? this.source,
+            sourceId: fact.sourceId,
+            sourceTimestamp: fact.sourceTimestamp,
+            tags: fact.tags,
+        };
+    }
+    /**
+     * Batch-validate an array of partial facts.
+     */
+    validateFacts(rawFacts) {
+        const facts = [];
+        let invalidCount = 0;
+        for (const raw of rawFacts) {
+            const validated = this.validateFact(raw);
+            if (validated) {
+                facts.push(validated);
+            }
+            else {
+                invalidCount++;
+            }
+        }
+        return { facts, invalidCount };
+    }
+}

package/dist/import-adapters/chatgpt-adapter.js

@@ -0,0 +1,238 @@
+import { BaseImportAdapter } from './base-adapter.js';
+import fs from 'node:fs';
+import os from 'node:os';
+/** Maximum messages per conversation chunk for LLM extraction. */
+const CHUNK_SIZE = 20;
+// ── ChatGPT Adapter ─────────────────────────────────────────────────────────
+export class ChatGPTAdapter extends BaseImportAdapter {
+    source = 'chatgpt';
+    displayName = 'ChatGPT';
+    async parse(input, onProgress) {
+        const warnings = [];
+        const errors = [];
+        let content;
+        if (input.content) {
+            content = input.content;
+        }
+        else if (input.file_path) {
+            try {
+                const resolvedPath = input.file_path.replace(/^~/, os.homedir());
+                content = fs.readFileSync(resolvedPath, 'utf-8');
+            }
+            catch (e) {
+                errors.push(`Failed to read file: ${e instanceof Error ? e.message : 'Unknown error'}`);
+                return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+            }
+        }
+        else {
+            errors.push('ChatGPT import requires either content (pasted text or JSON) or file_path. ' +
+                'Export from ChatGPT: Settings -> Data Controls -> Export Data (conversations.json), ' +
+                'or copy from Settings -> Personalization -> Memory -> Manage.');
+            return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+        }
+        // Detect format: JSON array = conversations.json, plain text = memories
+        const trimmed = content.trim();
+        if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+            // Try to parse as JSON (conversations.json or memory list)
+            return this.parseConversationsJson(trimmed, warnings, errors, onProgress);
+        }
+        // Plain text: ChatGPT memories (one per line)
+        return this.parseMemoriesText(trimmed, warnings, errors, onProgress);
+    }
+    /**
+     * Parse ChatGPT conversations.json — full export with mapping tree.
+     * Returns conversation chunks for LLM extraction (no pattern matching).
+     */
+    parseConversationsJson(content, warnings, errors, onProgress) {
+        let conversations;
+        try {
+            const data = JSON.parse(content);
+            if (Array.isArray(data)) {
+                conversations = data;
+            }
+            else if (data.conversations && Array.isArray(data.conversations)) {
+                conversations = data.conversations;
+            }
+            else if (data.mapping) {
+                // Single conversation object
+                conversations = [data];
+            }
+            else {
+                errors.push('Unrecognized ChatGPT format. Expected an array of conversation objects (conversations.json) ' +
+                    'or plain text (ChatGPT memories).');
+                return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+            }
+        }
+        catch (e) {
+            errors.push(`Failed to parse ChatGPT JSON: ${e instanceof Error ? e.message : 'Unknown error'}`);
+            return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+        }
+        if (onProgress) {
+            onProgress({
+                current: 0,
+                total: conversations.length,
+                phase: 'parsing',
+                message: `Parsing ${conversations.length} ChatGPT conversations...`,
+            });
+        }
+        const chunks = [];
+        let totalMessages = 0;
+        let convIndex = 0;
+        for (const conv of conversations) {
+            if (!conv.mapping) {
+                warnings.push(`Conversation "${conv.title || 'untitled'}" has no mapping — skipped`);
+                continue;
+            }
+            // Extract user + assistant messages in chronological order
+            const messages = this.extractMessages(conv.mapping);
+            if (messages.length === 0)
+                continue;
+            totalMessages += messages.length;
+            // Determine timestamp from first message or conversation
+            const timestamp = conv.create_time
+                ? new Date(conv.create_time * 1000).toISOString()
+                : undefined;
+            const title = conv.title || 'Untitled Conversation';
+            // Chunk into batches of CHUNK_SIZE messages
+            for (let i = 0; i < messages.length; i += CHUNK_SIZE) {
+                const batch = messages.slice(i, i + CHUNK_SIZE);
+                const chunkIndex = Math.floor(i / CHUNK_SIZE) + 1;
+                const totalChunks = Math.ceil(messages.length / CHUNK_SIZE);
+                chunks.push({
+                    title: totalChunks > 1 ? `${title} (part ${chunkIndex}/${totalChunks})` : title,
+                    messages: batch,
+                    timestamp,
+                });
+            }
+            convIndex++;
+            if (onProgress && convIndex % 50 === 0) {
+                onProgress({
+                    current: convIndex,
+                    total: conversations.length,
+                    phase: 'parsing',
+                    message: `Parsed ${convIndex}/${conversations.length} conversations (${chunks.length} chunks, ${totalMessages} messages)...`,
+                });
+            }
+        }
+        if (chunks.length === 0 && conversations.length > 0) {
+            warnings.push(`Parsed ${conversations.length} conversations but found no messages with text content.`);
+        }
+        return {
+            facts: [],
+            chunks,
+            totalMessages,
+            warnings,
+            errors,
+            source_metadata: {
+                format: 'conversations.json',
+                conversations_count: conversations.length,
+                chunks_count: chunks.length,
+                total_messages: totalMessages,
+            },
+        };
+    }
+    /**
+     * Parse ChatGPT memories — plain text, one memory per line.
+     * Users copy this from Settings -> Personalization -> Memory -> Manage.
+     *
+     * Each line becomes a single-message conversation chunk for LLM extraction.
+     */
+    parseMemoriesText(content, warnings, errors, onProgress) {
+        // Split by newlines and filter empty lines
+        const lines = content.split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            // Skip common header lines
+            .filter((line) => !/^(?:memories?|chatgpt memories?|my memories?|saved memories?):?\s*$/i.test(line));
+        if (onProgress) {
+            onProgress({
+                current: 0,
+                total: lines.length,
+                phase: 'parsing',
+                message: `Parsing ${lines.length} ChatGPT memories...`,
+            });
+        }
+        // Clean lines: strip bullet/dash/number markers
+        const cleanedLines = lines.map((line) => line
+            .replace(/^[-*\u2022]\s+/, '') // bullet points
+            .replace(/^\d+[.)]\s+/, '') // numbered lists
+            .trim()).filter((line) => line.length >= 3);
+        // Group all memories into chunks of CHUNK_SIZE for efficient LLM extraction
+        const chunks = [];
+        for (let i = 0; i < cleanedLines.length; i += CHUNK_SIZE) {
+            const batch = cleanedLines.slice(i, i + CHUNK_SIZE);
+            chunks.push({
+                title: `ChatGPT memories (${i + 1}-${Math.min(i + CHUNK_SIZE, cleanedLines.length)})`,
+                messages: batch.map((text) => ({ role: 'user', text })),
+            });
+        }
+        return {
+            facts: [],
+            chunks,
+            totalMessages: cleanedLines.length,
+            warnings,
+            errors,
+            source_metadata: {
+                format: 'memories-text',
+                total_lines: lines.length,
+                chunks_count: chunks.length,
+            },
+        };
+    }
+    /**
+     * Traverse the mapping tree and extract user + assistant messages in chronological order.
+     * Both roles are included because the assistant's response often provides context
+     * that helps the LLM understand what the user meant.
+     */
+    extractMessages(mapping) {
+        // Find the root node (the one with no parent or parent not in mapping)
+        let rootId;
+        for (const [id, node] of Object.entries(mapping)) {
+            if (!node.parent || !mapping[node.parent]) {
+                rootId = id;
+                break;
+            }
+        }
+        if (!rootId)
+            return [];
+        // Walk the tree breadth-first, following children in order (main thread)
+        const messages = [];
+        const visited = new Set();
+        const queue = [rootId];
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            if (visited.has(nodeId))
+                continue;
+            visited.add(nodeId);
+            const node = mapping[nodeId];
+            if (!node)
+                continue;
+            const role = node.message?.author?.role;
+            // Only collect user and assistant messages (skip system, tool)
+            if (role === 'user' || role === 'assistant') {
+                const textParts = this.extractTextFromParts(node.message?.content?.parts);
+                if (textParts && textParts.length >= 3) {
+                    messages.push({ role, text: textParts });
+                }
+            }
+            // Follow children (add them to queue in order)
+            for (const childId of node.children || []) {
+                queue.push(childId);
+            }
+        }
+        return messages;
+    }
+    /**
+     * Extract plain text from message content parts.
+     * Parts can be strings, null, or complex objects (images, etc.) -- we only want strings.
+     */
+    extractTextFromParts(parts) {
+        if (!parts || parts.length === 0)
+            return null;
+        const textParts = parts
+            .filter((p) => typeof p === 'string' && p.trim().length > 0);
+        if (textParts.length === 0)
+            return null;
+        return textParts.join(' ').trim();
+    }
+}