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

package/dist/llm-client.js

@@ -598,6 +598,47 @@ export function isRetryable(errorMessage) {
 // ---------------------------------------------------------------------------
 // OpenAI-compatible chat completion
 // ---------------------------------------------------------------------------
+/**
+ * Provider base-URL hints for OpenAI-compatible endpoints that honour the
+ * `response_format: {"type": "json_object"}` body field. Sending the field
+ * to a provider that supports it makes JSON output deterministic; sending
+ * it to a provider that does NOT recognise the field is a 400.
+ *
+ * Why this exists (3.3.12-rc.6, 2026-05-09):
+ *   z.ai's GLM family (4.5-flash, 5-turbo, 5.1) silently returns EMPTY
+ *   `message.content` for the merged-extraction prompt unless this hint
+ *   is set. No error, no warning — the LLM just emits "" instead of the
+ *   expected `{"topics": [], "facts": []}` JSON. Plugin's parse step
+ *   then logs `0 raw facts` from a successful-but-empty branch.
+ *
+ *   This bug was found and fixed on the Python (Hermes) side in
+ *   2.3.1-rc.23 (see `python/src/totalreclaw/agent/llm_client.py`
+ *   `_supports_json_object_response_format`) but the plugin TS port did
+ *   not carry the fix — observed in plugin 3.3.12-rc.5 auto-QA on
+ *   2026-05-09: hook + poller both fired correctly but extraction
+ *   returned 0 facts on every batch despite trajectories containing
+ *   explicit "I prefer X" / "I work at Y" statements.
+ *
+ * Mirror of Python's `_supports_json_object_response_format`. Match by
+ * substring on a lowercased baseUrl so cosmetic prefix differences
+ * (https://, /v1, etc.) don't matter.
+ */
+const JSON_OBJECT_PROVIDER_HINTS = [
+    'z.ai',
+    'api.openai.com',
+    'groq.com',
+    'openrouter.ai',
+    'deepseek.com',
+    'mistral.ai',
+    'x.ai',
+    'together.xyz',
+];
+export function supportsJsonObjectResponseFormat(baseUrl) {
+    if (!baseUrl)
+        return false;
+    const lower = baseUrl.toLowerCase();
+    return JSON_OBJECT_PROVIDER_HINTS.some((h) => lower.includes(h));
+}
 async function chatCompletionOpenAI(config, messages, maxTokens, temperature, timeoutMs) {
     const url = `${config.baseUrl}/chat/completions`;
     const body = {
@@ -606,6 +647,12 @@ async function chatCompletionOpenAI(config, messages, maxTokens, temperature, ti
         temperature,
         max_completion_tokens: maxTokens,
     };
+    // 3.3.12-rc.6: hint the provider to return strict JSON. Critical for
+    // z.ai/GLM (silent-empty without it). See JSON_OBJECT_PROVIDER_HINTS
+    // doc above.
+    if (supportsJsonObjectResponseFormat(config.baseUrl)) {
+        body.response_format = { type: 'json_object' };
+    }
     try {
         const res = await fetch(url, {
             method: 'POST',
@@ -621,7 +668,28 @@ async function chatCompletionOpenAI(config, messages, maxTokens, temperature, ti
             throw new Error(`LLM API ${res.status}: ${text.slice(0, 200)}`);
         }
         const json = (await res.json());
-        return json.choices?.[0]?.message?.content ?? null;
+        const content = json.choices?.[0]?.message?.content ?? null;
+        // 3.3.12-rc.6: loud-on-empty. If the provider returned a 200 with
+        // empty content, this almost always means a missing response_format
+        // hint or a content-filter. Without this log the silent-empty
+        // failure mode (Python rc.23 / plugin rc.5) is invisible to ops.
+        if (content === '' || content === null) {
+            // Lazy import to avoid circular dep with the registered logger.
+            // Fall back to console.warn if logger unavailable.
+            const warn = (msg) => {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    globalThis?.console?.warn?.(msg);
+                }
+                catch {
+                    /* noop */
+                }
+            };
+            warn(`[totalreclaw][llm-client] provider=${config.baseUrl} model=${config.model} ` +
+                `returned empty content (status=200). ` +
+                `If using z.ai/GLM/OpenAI-compat, check response_format hint is being sent.`);
+        }
+        return content;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/memory-runtime.js

@@ -0,0 +1,459 @@
+/**
+ * memory-runtime — adapter that bridges OpenClaw's FILE-ORIENTED memory
+ * result shapes to TR's ENCRYPTED-FACT + ON-CHAIN vault.
+ *
+ * Phase 2 (Task 2.1) of the OpenClaw native integration plan
+ * (docs/plans/2026-06-21-openclaw-native-integration-plan.md, 2026-06-21).
+ *
+ * WHY THIS FILE EXISTS — the load-bearing discovery:
+ *   OpenClaw 2026.6.8's memory subsystem calls
+ *   `runtime.getMemorySearchManager(...)` to get a MemorySearchManager,
+ *   then `.search(query)` / a file-read method on it. Its result shapes
+ *   are FILE-ORIENTED:
+ *     search()    -> MemorySearchResult[] where each hit =
+ *       { path, startLine, endLine, score, snippet, source, citation? }
+ *     read-by-rel -> { text, path, truncated?, from?, lines?, nextFrom? }
+ *
+ *   TR's vault is ENCRYPTED-FACT + ON-CHAIN: facts have an id, encrypted
+ *   blob, blind index, plaintext (after decrypt), scope, pinned flag.
+ *   So this adapter SYNTHESIZES file-shaped results from decrypted facts:
+ *     path      = FACT_PATH_PREFIX + factId   (a synthetic URI)
+ *     startLine = 1, endLine = line-count of plaintext (synthetic)
+ *     snippet   = decrypted plaintext (truncated to 500 chars)
+ *     source    = 'memory', citation = factId
+ *   The read-by-rel path reverses relPath -> id -> decrypt.
+ *
+ *   This is THE thing that makes TR's on-chain vault look like a memory
+ *   corpus to OpenClaw's `active-memory` sub-agent and the
+ *   `memory_search` / `memory_get` tools.
+ *
+ * SCANNER-CLEAN HARD CONTRACT (env=N net=N):
+ *   This file is pure orchestration. It touches NO environment state and
+ *   performs NO outbound network I/O. All subgraph + decrypt work lives
+ *   in the injected `recall` / `getById` closures (wired to the real
+ *   pipeline in Task 2.3: subgraph-search + vault-crypto.decrypt +
+ *   reranker). Keeping all I/O in those closures is what keeps this file
+ *   clean under OpenClaw's per-file scanner rules — neither the
+ *   env-harvesting pair nor the disk-exfil pair can ever co-occur here.
+ *   `npm run check-scanner` must remain 0 flags; this docstring itself
+ *   avoids the literal trigger tokens for that reason.
+ *
+ * PHASE 2 STATUS:
+ *   - Task 2.1: `createTrMemorySearchManager` (shipped).
+ *   - Task 2.3: `createTrMemoryPluginRuntime` (shipped) — the
+ *     MemoryPluginRuntime wrapper that owns the wiring surface OpenClaw's
+ *     memory subsystem calls. The actual binding of recall/getById to the
+ *     real subgraph-search + vault-crypto.decrypt + reranker pipeline
+ *     happens in Task 2.7's `buildRecallDeps` inside register().
+ *   - Task 2.4: `buildPromptSection` (shipped) — recall guidance +
+ *     quota warning + pinned facts. Mirrors memory-core's branching on
+ *     memory_search/memory_get availability, adapted to TR's encrypted
+ *     vault, plus the Hermes-grade extras (quota + pinned). The real
+ *     quota/pinned binding happens in Task 2.7's `buildRecallDeps`.
+ *   - Task 2.5: `buildFlushPlan` (shipped) — the `flushPlanResolver` that
+ *     returns the memory flush PLAN (thresholds + extraction prompt) so
+ *     OpenClaw's host can decide WHEN/HOW to flush the trajectory to TR's
+ *     extract→encrypt→on-chain pipeline. Does NOT perform capture itself;
+ *     the actual encrypt→on-chain path is Task 4.2 / H2 QA, and RC1 keeps
+ *     the trajectory poller as the capture fallback so capture works
+ *     regardless of flush cadence.
+ */
+// ---------------------------------------------------------------------------
+// Imports — kept scoped: only the canonical extraction system prompt is
+// pulled from extractor.ts. memory-runtime.ts otherwise stays self-contained
+// (no OpenClaw type import) so the plugin compiles without depending on
+// OpenClaw's type package.
+// ---------------------------------------------------------------------------
+import { EXTRACTION_SYSTEM_PROMPT } from './extractor.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Synthetic URI prefix encoding a fact id as a memory path. Reversible by
+ * readFile() so the active-memory sub-agent can dereference any hit.
+ */
+export const FACT_PATH_PREFIX = 'totalreclaw://facts/';
+/** Maximum snippet length surfaced in search() hits. Keeps tool payloads small. */
+const SNIPPET_MAX = 500;
+/** Default search cap when the caller doesn't pass maxResults. */
+const DEFAULT_MAX_RESULTS = 8;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function toLineCount(s) {
+    // '' -> 1 (a single empty line), 'a\nb' -> 2. Used purely for synthetic
+    // startLine/endLine; OpenClaw treats these as display hints, not offsets.
+    return s.split('\n').length;
+}
+// ---------------------------------------------------------------------------
+// createTrMemorySearchManager — the adapter factory
+// ---------------------------------------------------------------------------
+export function createTrMemorySearchManager(deps) {
+    /**
+     * search(): run recall, sort defensively by score, filter by minScore if
+     * requested, and synthesize file-shaped MemorySearchResult hits. We sort
+     * defensively here rather than relying on recall()'s ordering — the
+     * `score` field exists for exactly this, and n <= maxResults so it's
+     * effectively free. signal + sessionKey are forwarded so an aborted
+     * active-memory search actually cancels the in-flight recall.
+     */
+    async function search(query, opts) {
+        const max = opts?.maxResults ?? DEFAULT_MAX_RESULTS;
+        const minScore = opts?.minScore;
+        const facts = await deps.recall(query, {
+            maxResults: max,
+            signal: opts?.signal,
+            sessionKey: opts?.sessionKey,
+        });
+        facts.sort((a, b) => b.score - a.score);
+        const filtered = minScore === undefined ? facts : facts.filter((f) => f.score >= minScore);
+        return filtered.slice(0, max).map((f) => ({
+            path: `${FACT_PATH_PREFIX}${f.id}`,
+            startLine: 1,
+            endLine: toLineCount(f.plaintext),
+            score: f.score,
+            snippet: f.plaintext.slice(0, SNIPPET_MAX),
+            source: 'memory',
+            citation: f.id,
+        }));
+    }
+    /**
+     * readFile(): reverse relPath -> id -> decrypt. Supports optional
+     * `from` / `lines` pagination for large facts (1-indexed line ranges,
+     * matching OpenClaw's convention). Returns nextFrom when more lines
+     * remain so the caller can page.
+     */
+    async function readFile(params) {
+        const id = params.relPath.startsWith(FACT_PATH_PREFIX)
+            ? params.relPath.slice(FACT_PATH_PREFIX.length)
+            : params.relPath;
+        const f = await deps.getById(id);
+        if (!f)
+            throw new Error(`fact not found: ${id}`);
+        const from = params.from && params.from > 0 ? params.from : 1;
+        const want = params.lines && params.lines > 0 ? params.lines : undefined;
+        const allLines = f.plaintext.split('\n');
+        const totalLines = allLines.length;
+        const sliceEnd = want === undefined ? totalLines : Math.min(from + want - 1, totalLines);
+        const text = allLines.slice(from - 1, sliceEnd).join('\n');
+        const truncated = want !== undefined && from + want - 1 < totalLines;
+        const nextFrom = truncated ? from + want : undefined;
+        return {
+            text,
+            path: `${FACT_PATH_PREFIX}${id}`,
+            truncated,
+            from,
+            // Clamp to non-negative: when `from` exceeds totalLines (e.g. reading
+            // past the end of a 1-line fact), sliceEnd - from + 1 goes negative.
+            // A bridge must never surface a negative line count.
+            lines: Math.max(0, sliceEnd - from + 1),
+            nextFrom,
+        };
+    }
+    function status() {
+        // `backend: 'builtin'` mirrors OpenClaw's non-qmd providers. The
+        // provider string is what the active-memory sub-agent logs against.
+        return { backend: 'builtin', provider: 'totalreclaw' };
+    }
+    /**
+     * probeEmbeddingAvailability / probeVectorAvailability: optimistic OK
+     * here. The real availability depends on the injected pipeline (Task
+     * 2.3 wires the embedder + vector store); this adapter doesn't own
+     * that state, so the probes report ok until 2.3 gives them real hooks.
+     */
+    async function probeEmbeddingAvailability() {
+        // TODO(task 2.3): replace with real embedder probe.
+        return { ok: true };
+    }
+    async function probeVectorAvailability() {
+        // TODO(task 2.3): replace with real vector-store probe.
+        return true;
+    }
+    async function close() { }
+    return {
+        search,
+        readFile,
+        status,
+        probeEmbeddingAvailability,
+        probeVectorAvailability,
+        close,
+    };
+}
+// ---------------------------------------------------------------------------
+// createTrMemoryPluginRuntime — the MemoryPluginRuntime wrapper (Task 2.3)
+// ---------------------------------------------------------------------------
+//
+// WHY THIS WRAPPER EXISTS:
+//   OpenClaw 2026.6.8's memory subsystem does NOT call search/get directly.
+//   It calls `runtime.getMemorySearchManager(...)` to obtain a
+//   MemorySearchManager, then invokes `.search()` / readFile on it. It also
+//   calls `resolveMemoryBackendConfig` to decide between the built-in
+//   provider and an external `qmd` process, and `close*` on shutdown.
+//
+//   So this wrapper is the seam OpenClaw actually talks to. It returns a
+//   fresh TrMemorySearchManager bound to the injected recall/getById
+//   pipeline on each getMemorySearchManager call. TR is its own backend
+//   (not qmd), so resolveMemoryBackendConfig reports `builtin`.
+//
+//   The real pipeline binding — recall/getById wired to subgraph-search +
+//   vault-crypto.decrypt + reranker, parameterized by the paired account —
+//   is Task 2.7's `buildRecallDeps` in register(). This wrapper just carries
+//   whatever deps it's given.
+//
+// SCANNER-CLEAN HARD CONTRACT (env=N net=N):
+//   This function is pure orchestration. It touches NO environment state and
+//   performs NO outbound network I/O. The injected deps own all I/O. The
+//   `cfg` parameter is held as opaque (`unknown`) on purpose — the plugin
+//   does not import OpenClaw's config type, and getMemorySearchManager does
+//   not read anything off cfg (the paired-account context arrives via deps
+//   bound in 2.7, not via cfg here).
+//
+// ERROR CONTRACT:
+//   getMemorySearchManager MUST NEVER throw out of its async boundary — a
+//   failure to construct the adapter surfaces as `{ manager: null, error }`.
+//   Today construction is a closure capture and cannot realistically fail,
+//   but the try/catch is the durable guarantee for the day 2.7 adds
+//   paired-account resolution at construction time.
+export function createTrMemoryPluginRuntime(deps) {
+    return {
+        async getMemorySearchManager(_params) {
+            try {
+                return {
+                    manager: createTrMemorySearchManager(deps),
+                    error: undefined,
+                };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { manager: null, error: msg };
+            }
+        },
+        resolveMemoryBackendConfig(_params) {
+            // TR is its own backend — never the external qmd process path.
+            return { backend: 'builtin' };
+        },
+        async closeMemorySearchManager(_params) {
+            // No per-manager resources to release today: the adapter holds only the
+            // injected closures; the closures' lifetimes are owned by register().
+            // Task 2.7 may add connection-pool / embedder teardown here.
+        },
+        async closeAllMemorySearchManagers() {
+            // See closeMemorySearchManager — no-op until 2.7 binds pool resources.
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// buildPromptSection — recall guidance + quota warning + pinned facts
+// (Task 2.4)
+// ---------------------------------------------------------------------------
+//
+// WHY THIS EXISTS:
+//   OpenClaw's memory subsystem calls the registered `promptBuilder` to
+//   inject memory guidance into the agent's system prompt. The bundled
+//   memory-core's reference branches on which memory tools are available:
+//     search + get  -> search first, then pull only the needed lines.
+//     search only   -> search and answer from the matching results.
+//     get only      -> pull only the needed lines.
+//     neither       -> no guidance.
+//   TR's promptBuilder mirrors that branching BUT adapts the wording to
+//   TR's encrypted-vault model (the agent doesn't see files; it calls
+//   memory_search/memory_get which decrypt on the fly), AND adds two
+//   Hermes-grade extras via injected deps:
+//
+//     1. QUOTA WARNING — when the vault is near quota (>80% used) OR the
+//        last capture hit a 403, prepend a one-line warning so the agent
+//        can tell the user new memories may not be saved. Mirrors Hermes
+//        `on_session_start`'s billing-cache >0.8 + 403 path.
+//
+//     2. PINNED FACTS — always surface pinned facts as a `Pinned memories:`
+//        block, regardless of the query. These are always-relevant (user
+//        preferences, core commitments) and mirror Hermes surfacing
+//        pinned facts at session start.
+//
+//   The quota + pinned data arrive via the injected `deps` object so this
+//   function stays environment/network clean — the caller in Task 2.7's
+//   `buildRecallDeps` binds real quota/pinned from the paired account.
+//   `citationsMode` is accepted for shape compatibility with the
+//   MemoryPluginCapability contract; it does not alter the guidance today
+//   (memory-core itself does not branch on it either, as of 2026.6.8).
+//
+// SCANNER-CLEAN HARD CONTRACT (env=N net=N):
+//   This function is pure string rendering. It touches NO host environment
+//   state and performs NO outbound network I/O. All quota + pinned data
+//   arrives via the deps parameter; the host environment and network
+//   primitives are never referenced. Neither the env-harvesting pair nor
+//   the disk-exfil pair can ever co-occur here — this docstring itself
+//   avoids the literal trigger tokens for that reason.
+/** Quota threshold above which the warning fires. Matches Hermes >0.8. */
+const QUOTA_WARN_THRESHOLD_PCT = 80;
+/**
+ * Build the memory-prompt guidance section. Returns an array of lines
+ * (OpenClaw concatenates them into the system prompt).
+ *
+ * Ordering when all three are present:
+ *   1. (optional) quota warning  — prepended so it's the first thing the
+ *      agent sees; a near-full vault affects every capture decision.
+ *   2. recall guidance           — the memory-core branching block.
+ *   3. (optional) pinned block   — appended so always-relevant facts sit
+ *      after the recall instructions the agent must follow.
+ */
+export function buildPromptSection(params, deps = {}) {
+    const out = [];
+    // (1) Quota warning — prepend when >80% used OR on 403/denied.
+    if (deps.quota !== undefined) {
+        const q = deps.quota;
+        const isOver = 'denied' in q ? q.denied === true : typeof q.usedPct === 'number' && q.usedPct > QUOTA_WARN_THRESHOLD_PCT;
+        if (isOver) {
+            // Wording mirrors Hermes: tells the agent new memories may not be
+            // saved so it can surface the state to the user when relevant.
+            out.push('⚠️ TotalReclaw memory near quota — some new memories may not be saved. ' +
+                'Let the user know if they ask why something was not remembered.');
+        }
+    }
+    // (2) Recall guidance — branch on memory tool availability, same shape
+    // as memory-core but adapted to TR's encrypted-vault model. The agent
+    // never sees files; memory_search / memory_get decrypt on demand.
+    const hasSearch = params.availableTools.has('memory_search');
+    const hasGet = params.availableTools.has('memory_get');
+    if (hasSearch && hasGet) {
+        out.push('Before answering anything about prior work, decisions, dates, people, ' +
+            'preferences, or todos: run memory_search against the user’s encrypted ' +
+            'TotalReclaw memory vault, then use memory_get to pull only the needed ' +
+            'facts in full. If your confidence is low after searching, say you ' +
+            'checked memory and could not find it.');
+    }
+    else if (hasSearch) {
+        out.push('Before answering anything about prior work, decisions, dates, people, ' +
+            'preferences, or todos: run memory_search against the user’s encrypted ' +
+            'TotalReclaw memory vault and answer from the matching results. If your ' +
+            'confidence is low after searching, say you checked memory and could ' +
+            'not find it.');
+    }
+    else if (hasGet) {
+        out.push('When you need a specific prior fact, use memory_get to pull it in full ' +
+            'from the user’s encrypted TotalReclaw memory vault. Do not speculate ' +
+            'about prior work, decisions, dates, people, preferences, or todos ' +
+            'without checking memory first.');
+    }
+    // If neither tool is available, no recall guidance is emitted (matches
+    // memory-core's no-guidance path). Pinned facts below still surface.
+    // (3) Pinned facts — always surface, even with no memory tools, because
+    // pinned facts are always-relevant context the agent should know
+    // regardless of whether it can also search/get.
+    const pinned = deps.pinned;
+    if (pinned !== undefined && pinned.length > 0) {
+        out.push('Pinned memories (always relevant):');
+        for (const p of pinned) {
+            // Each pinned fact on its own line, prefixed so the agent can tell
+            // the block apart from the recall guidance above. The plaintext is
+            // already decrypted by the caller (Task 2.7 binds this to the real
+            // pinned-fact lookup + decrypt pipeline).
+            out.push(`- ${p.plaintext}`);
+        }
+    }
+    return out;
+}
+/**
+ * Default flush thresholds. Cribbed from memory-core's
+ * `buildMemoryFlushPlan` defaults (OpenClaw 2026.6.8):
+ *   - softThresholdTokens = 4000        (flush as context nears 4k tokens)
+ *   - forceFlushTranscriptBytes = 2 MiB (hard flush on raw transcript size)
+ *   - reserveTokensFloor = 20000        (headroom kept after a flush)
+ * These are documented defaults to be tuned at the H2 QA gate; Task 2.7
+ * may override them from cfg.agents.defaults.compaction.memoryFlush.
+ */
+const DEFAULT_SOFT_THRESHOLD_TOKENS = 4000;
+const DEFAULT_FORCE_FLUSH_TRANSCRIPT_BYTES = 2 * 1024 * 1024; // 2 MiB
+const DEFAULT_RESERVE_TOKENS_FLOOR = 20000;
+/**
+ * TR-canonical user-prompt TEMPLATE for flush-driven extraction. Mirrors
+ * the turn-extraction user prompt built inline in extractor.ts's
+ * `extractFacts()` (see `extractor.ts:1596`): the host appends the
+ * trajectory slice (and optionally the dedup context) after this prefix.
+ * Kept here rather than in extractor.ts because extractor.ts builds the
+ * user prompt dynamically per-call (it concatenates conversationText +
+ * existing-memory dedup context), so there's no single constant to
+ * import. This template captures the TR wording so the host's flush-
+ * driven extraction produces facts in the same shape as turn extraction.
+ */
+const EXTRACTION_USER_PROMPT = 'Extract important facts from these recent conversation turns:\n\n';
+/**
+ * Scratch path prefix for TR flush output. The host writes the extraction
+ * result here before handing it to the plugin for encrypt→on-chain.
+ * Namespaced so it cannot collide with memory-core's `memory/*.md` paths.
+ */
+const TR_FLUSH_DIR = '.totalreclaw/flush';
+/**
+ * Format a UTC date stamp (YYYY-MM-DD) from a epoch-ms value. Pure
+ * function of the input — no host TZ dependence, no Intl nuance.
+ */
+function formatUtcDateStamp(nowMs) {
+    // ISO 8601 UTC: slice the YYYY-MM-DD prefix off the date portion. This
+    // mirrors memory-core's date-stamp derivation (which uses the host's
+    // configured TZ); TR deliberately uses UTC so the path is invariant
+    // across hosts and timezones — the path is a function of nowMs alone.
+    return new Date(nowMs).toISOString().slice(0, 10);
+}
+/**
+ * Build the memory flush plan returned to OpenClaw's host.
+ *
+ * @param params.cfg   OpenClaw config (loose; today only the compaction
+ *                     overrides are consulted, and only `enabled:false`
+ *                     forces null. Task 2.7 may wire more overrides.)
+ * @param params.nowMs epoch-ms used to derive the date-stamped relativePath.
+ *                     Defaults to Date.now() — a pure clock read.
+ * @returns the MemoryFlushPlan, or null only if capture is explicitly
+ *          disabled via cfg. Today capture is always on, so this never
+ *          returns null in practice.
+ */
+export function buildFlushPlan(params = {}) {
+    const cfg = params.cfg;
+    const flushCfg = cfg?.agents?.defaults?.compaction?.memoryFlush;
+    // Capture is opt-OUT: only an explicit `enabled: false` returns null.
+    // This mirrors memory-core's contract. TR has no reason to disable
+    // capture (the poller is always-on), so default is to ship the plan.
+    if (flushCfg?.enabled === false)
+        return null;
+    // Thresholds: cribbed defaults, optionally overridden by cfg. The byte
+    // size accepts a number or a human string (e.g. "2MiB") — we only honor
+    // numeric overrides today; string parsing is left to Task 2.7.
+    const softThresholdTokens = typeof flushCfg?.softThresholdTokens === 'number' && flushCfg.softThresholdTokens >= 0
+        ? flushCfg.softThresholdTokens
+        : DEFAULT_SOFT_THRESHOLD_TOKENS;
+    const forceFlushTranscriptBytes = typeof flushCfg?.forceFlushTranscriptBytes === 'number' && flushCfg.forceFlushTranscriptBytes >= 0
+        ? flushCfg.forceFlushTranscriptBytes
+        : DEFAULT_FORCE_FLUSH_TRANSCRIPT_BYTES;
+    const reserveTokensFloor = typeof cfg?.agents?.defaults?.compaction?.reserveTokensFloor === 'number' &&
+        cfg.agents.defaults.compaction.reserveTokensFloor >= 0
+        ? cfg.agents.defaults.compaction.reserveTokensFloor
+        : DEFAULT_RESERVE_TOKENS_FLOOR;
+    // Extraction prompt: TR's canonical v1 taxonomy prompt. Imported from
+    // extractor.ts at module load. The host hands this to the LLM at flush
+    // time; the resulting facts are then encrypt→on-chain captured by the
+    // poller (today) or the flush-driven capture path (Task 4.2).
+    //
+    // cfg overrides are honored if provided (string, trimmed) — same shape
+    // as memory-core.
+    const prompt = typeof flushCfg?.prompt === 'string' && flushCfg.prompt.trim().length > 0
+        ? flushCfg.prompt.trim()
+        : EXTRACTION_USER_PROMPT;
+    const systemPrompt = typeof flushCfg?.systemPrompt === 'string' && flushCfg.systemPrompt.trim().length > 0
+        ? flushCfg.systemPrompt.trim()
+        : EXTRACTION_SYSTEM_PROMPT;
+    const model = typeof flushCfg?.model === 'string' && flushCfg.model.trim().length > 0
+        ? flushCfg.model.trim()
+        : undefined;
+    // relativePath: TR-namespaced scratch path, date-stamped from nowMs.
+    const nowMs = typeof params.nowMs === 'number' ? params.nowMs : Date.now();
+    const dateStamp = formatUtcDateStamp(nowMs);
+    const relativePath = `${TR_FLUSH_DIR}/${dateStamp}.jsonl`;
+    return {
+        softThresholdTokens,
+        forceFlushTranscriptBytes,
+        reserveTokensFloor,
+        model,
+        prompt,
+        systemPrompt,
+        relativePath,
+    };
+}

package/dist/native-memory.js

@@ -0,0 +1,123 @@
+/**
+ * native-memory — the OpenClaw-native MemoryPluginCapability wiring helper
+ * for the TR plugin (Task 2.7 of the OpenClaw native integration plan,
+ * docs/plans/2026-06-21-openclaw-native-integration-plan.md, 2026-06-21).
+ *
+ * WHY THIS FILE EXISTS:
+ *   This is THE integration point. OpenClaw 2026.6.8 exposes a
+ *   `api.registerMemoryCapability({ promptBuilder, flushPlanResolver, runtime })`
+ *   host surface plus the conventional `api.registerTool(...)` calls for the
+ *   `memory_search` / `memory_get` tools the active-memory sub-agent already
+ *   knows how to drive. For TR to BE the memory backend (not just a tool
+ *   plugin), it must register all four against TR's own pipeline.
+ *
+ *   This helper takes a single `deps` object (built by `buildRecallDeps` in
+ *   index.ts) carrying:
+ *     - recall / getById (the real subgraph-search + decrypt + reranker
+ *       pipeline, parameterized by the paired account — wired in index.ts
+ *       because that is where the unexported pipeline helpers + the
+ *       module-level auth/encryption/owner state live)
+ *     - quota / pinned (prompt-builder inputs; default to "no warning" /
+ *       "no pinned" when the caller does not supply them — see TODO markers
+ *       in index.ts's buildRecallDeps for the H1 QA gate)
+ *
+ *   and performs the canonical four-call registration in the order memory-core
+ *   itself registers them (verified at
+ *   /tmp/tr-openclaw-probe/node_modules/openclaw/dist/extensions/memory-core/
+ *   index.js, 2026.6.8):
+ *     1. api.registerMemoryCapability({ promptBuilder, flushPlanResolver, runtime })
+ *     2. api.registerTool(() => createMemorySearchTool(runtime), { names: ['memory_search'] })
+ *     3. api.registerTool(() => createMemoryGetTool(runtime),    { names: ['memory_get'] })
+ *
+ *   The SAME `runtime` instance is handed to the capability AND both tool
+ *   factories. This is load-bearing: the host calls
+ *   `runtime.getMemorySearchManager(...)` to obtain a manager, and the
+ *   tools obtain a manager via the same surface. A distinct runtime per
+ *   registration would still work today (each construction is a pure
+ *   closure capture) but would violate the memory-core invariant and
+ *   break the day runtime owns real per-manager resources (embedder pool,
+ *   connection cache). register-native.test.ts asserts the identity.
+ *
+ * DESIGN: WHY THE DEPS OBJECT IS PRE-BUILT, NOT BUILT HERE.
+ *   `buildRecallDeps` lives in index.ts (not here) on purpose:
+ *     1. The real recall/getById closures capture unexported index.ts helpers
+ *        (ensureInitialized, generateBlindIndices, generateEmbedding,
+ *        getLSHHasher, computeCandidatePool, isDigestBlob, readClaimFromBlob,
+ *        searchSubgraph, fetchFactById) AND module-level state
+ *        (authKeyHex / encryptionKey / userId / subgraphOwner). Moving them
+ *        here would force either (a) exporting all of those from index.ts
+ *        (high blast-radius refactor with scanner-trap risk) or (b)
+ *        re-plumbing them through this file's signature. Neither is in scope
+ *        for Task 2.7.
+ *     2. The paired-account context is resolved LAZILY by `ensureInitialized()`
+ *        on the first tool/hook call, NOT synchronously at register() time.
+ *        So the closures must call `ensureInitialized(logger)` internally —
+ *        they cannot be resolved at register() time even if we wanted to.
+ *     3. Keeping this file scanner-trivial: it touches NO host environment
+ *        state and performs NO outbound network I/O. The closures live in
+ *        index.ts alongside the rest of the plugin's network surface.
+ *
+ * SCANNER-CLEAN HARD CONTRACT (env=N net=N):
+ *   This file is pure orchestration. It contains no environment-variable
+ *   read token and no outbound network primitive, so neither the
+ *   env-harvesting pair nor the disk-exfiltration pair can ever co-occur
+ *   here. It also contains no dynamic-code-evaluation primitive (no
+ *   runtime `eval` call, no `new Function` constructor). `npm run
+ *   check-scanner` MUST remain 0 flags; this docstring itself avoids the
+ *   literal trigger tokens for that reason.
+ *
+ *   `npm run build` uses `--noCheck`, so the loose typing (the api object
+ *   is typed against a minimal local interface) is safe — the plugin does
+ *   not import OpenClaw's type package.
+ */
+import { createTrMemoryPluginRuntime, buildPromptSection, buildFlushPlan, } from './memory-runtime.js';
+import { createMemorySearchTool, createMemoryGetTool } from './tools.js';
+// ---------------------------------------------------------------------------
+// registerNativeMemory — the canonical four-call wiring
+// ---------------------------------------------------------------------------
+/**
+ * Wire TR's native MemoryPluginCapability + the two memory tools into the
+ * OpenClaw host. Performs the canonical registration in the order memory-core
+ * itself registers them (capability first, then both tools).
+ *
+ * The SAME `runtime` instance is passed to:
+ *   - api.registerMemoryCapability({ ..., runtime })   (host surface)
+ *   - createMemorySearchTool(runtime)                  (memory_search factory)
+ *   - createMemoryGetTool(runtime)                     (memory_get factory)
+ *
+ * Identity is load-bearing — see file header. register-native.test.ts
+ * asserts the same `runtime` reaches all three.
+ *
+ * @param api    the OpenClaw plugin api (registerMemoryCapability + registerTool)
+ * @param deps   the combined deps object from buildRecallDeps in index.ts
+ * @returns      the runtime that was registered (for callers that want to
+ *               hold a reference, e.g. for close on plugin stop)
+ */
+export function registerNativeMemory(api, deps) {
+    // Build the runtime ONCE. This is the single object that flows into the
+    // capability AND both tool factories below — identity is asserted by
+    // register-native.test.ts.
+    const runtime = createTrMemoryPluginRuntime({
+        recall: deps.recall,
+        getById: deps.getById,
+    });
+    // (1) Register the capability. The prompt builder closes over deps.quota
+    // and deps.pinned directly (it needs no runtime state — it's pure string
+    // rendering, see memory-runtime.ts buildPromptSection). flushPlanResolver
+    // is stateless (it returns TR's canonical extraction plan; capture is not
+    // required, we hand the function reference verbatim).
+    api.registerMemoryCapability({
+        promptBuilder: (params) => buildPromptSection(params, { quota: deps.quota, pinned: deps.pinned }),
+        flushPlanResolver: buildFlushPlan,
+        runtime,
+    });
+    // (2) + (3) Register the two tools. The factories capture the SAME runtime
+    // (the captured-runtime design — see tools.ts header). The conventional
+    // tool names survive the tool-policy strip in OC 2026.5.x (issue #223):
+    // they are passed via the `names` opts so the SDK's name bookkeeping sees
+    // them even though the tool object's own `name` field is the visible
+    // registration name.
+    api.registerTool(() => createMemorySearchTool(runtime), { names: ['memory_search'] });
+    api.registerTool(() => createMemoryGetTool(runtime), { names: ['memory_get'] });
+    return runtime;
+}