dsh-tdai-memory 0.1.0

package/vendor/tdai/utils/clean-context-runner.js

@@ -0,0 +1,472 @@
+/**
+ * CleanContextRunner: executes LLM calls in a fully isolated context
+ * using runEmbeddedPiAgent (same mechanism as the llm-task extension).
+ *
+ * Guarantees:
+ * 1. Blank conversation history (temporary session file)
+ * 2. Independent system prompt (only the task prompt)
+ * 3. No tool calls when enableTools=false (disableTools:true — no tool definitions sent to API)
+ * 4. No contamination from the main agent's context
+ */
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { getEnv } from "./env.js";
+import { report } from "../core/report/reporter.js";
+/**
+ * Resolve a preferred temporary directory for memory-tdai operations.
+ *
+ * Previously imported from `openclaw/plugin-sdk` as `resolvePreferredOpenClawTmpDir`,
+ * but that export was removed in openclaw 2026.2.23+. This local implementation
+ * provides equivalent behavior:
+ *   1. Try `/tmp/openclaw` (if writable)
+ *   2. Fall back to `os.tmpdir()/openclaw-<uid>`
+ */
+function resolveOpenClawTmpDir() {
+    const POSIX_DIR = "/tmp/openclaw";
+    try {
+        if (fsSync.existsSync(POSIX_DIR)) {
+            fsSync.accessSync(POSIX_DIR, fsSync.constants.W_OK | fsSync.constants.X_OK);
+            return POSIX_DIR;
+        }
+        // Try to create it
+        fsSync.mkdirSync(POSIX_DIR, { recursive: true, mode: 0o700 });
+        return POSIX_DIR;
+    }
+    catch {
+        // Fall back to os.tmpdir()
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+        const suffix = uid === undefined ? "openclaw" : `openclaw-${uid}`;
+        const fallback = path.join(os.tmpdir(), suffix);
+        fsSync.mkdirSync(fallback, { recursive: true });
+        return fallback;
+    }
+}
+const TAG = "[memory-tdai] [runner]";
+let _preferredAgentRuntime;
+export function setPreferredEmbeddedAgentRuntime(agentRuntime) {
+    _preferredAgentRuntime = agentRuntime;
+}
+function resolveInjectedRunEmbeddedPiAgent(agentRuntime) {
+    const candidate = agentRuntime?.runEmbeddedPiAgent ?? _preferredAgentRuntime?.runEmbeddedPiAgent;
+    return typeof candidate === "function" ? candidate : undefined;
+}
+async function resolveRunEmbeddedPiAgent(agentRuntime, logger) {
+    const injected = resolveInjectedRunEmbeddedPiAgent(agentRuntime);
+    if (injected) {
+        logger?.debug?.(`${TAG} resolveRunEmbeddedPiAgent: using injected runtime.agent.runEmbeddedPiAgent`);
+        logger?.debug?.(`${TAG} [l1-debug] RESOLVE source=injected`);
+        return injected;
+    }
+    logger?.debug?.(`${TAG} [l1-debug] RESOLVE source=dist-fallback`);
+    return loadRunEmbeddedPiAgent(logger);
+}
+// ── Core import (mirrors voice-call/core-bridge.ts — dist/ only, no jiti) ──
+let _rootCache = null;
+function findPackageRoot(startDir, name) {
+    let dir = startDir;
+    for (;;) {
+        const pkgPath = path.join(dir, "package.json");
+        try {
+            if (fsSync.existsSync(pkgPath)) {
+                const raw = fsSync.readFileSync(pkgPath, "utf8");
+                const pkg = JSON.parse(raw);
+                if (pkg.name === name)
+                    return dir;
+            }
+        }
+        catch { /* ignore */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function resolveOpenClawRoot() {
+    if (_rootCache)
+        return _rootCache;
+    const override = getEnv("OPENCLAW_ROOT")?.trim();
+    if (override) {
+        _rootCache = override;
+        return override;
+    }
+    const candidates = new Set();
+    if (process.argv[1])
+        candidates.add(path.dirname(process.argv[1]));
+    candidates.add(process.cwd());
+    try {
+        candidates.add(path.dirname(fileURLToPath(import.meta.url)));
+    }
+    catch { /* ignore */ }
+    for (const start of candidates) {
+        const found = findPackageRoot(start, "openclaw");
+        if (found) {
+            _rootCache = found;
+            return found;
+        }
+    }
+    throw new Error("Unable to resolve OpenClaw root. Set OPENCLAW_ROOT or run `pnpm build`.");
+}
+let _loadPromise = null;
+function loadRunEmbeddedPiAgent(logger) {
+    if (_loadPromise)
+        return _loadPromise;
+    _loadPromise = (async () => {
+        const t0 = Date.now();
+        const distPath = path.join(resolveOpenClawRoot(), "dist", "extensionAPI.js");
+        if (!fsSync.existsSync(distPath)) {
+            throw new Error(`Missing core module at ${distPath}. Run \`pnpm build\` or install the official package.`);
+        }
+        const mod = await import(pathToFileURL(distPath).href);
+        if (typeof mod.runEmbeddedPiAgent !== "function") {
+            throw new Error("runEmbeddedPiAgent not exported from dist/extensionAPI.js");
+        }
+        logger?.info(`${TAG} loadRunEmbeddedPiAgent: dist/ import OK (${Date.now() - t0}ms)`);
+        return mod.runEmbeddedPiAgent;
+    })();
+    _loadPromise.catch(() => { _loadPromise = null; });
+    return _loadPromise;
+}
+/**
+ * Pre-warm the embedded agent import. Call this during plugin init to avoid
+ * the cold-start penalty on the first actual extraction run.
+ * Returns immediately (fire-and-forget) — errors are swallowed.
+ */
+export function prewarmEmbeddedAgent(logger, agentRuntime) {
+    if (resolveInjectedRunEmbeddedPiAgent(agentRuntime)) {
+        logger?.debug?.(`${TAG} prewarmEmbeddedAgent: runtime capability already available, skipping legacy preload`);
+        return;
+    }
+    loadRunEmbeddedPiAgent(logger).catch((err) => {
+        logger?.warn(`${TAG} prewarmEmbeddedAgent: failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
+function collectText(payloads) {
+    const texts = (payloads ?? [])
+        .filter((p) => !p.isError && typeof p.text === "string")
+        .map((p) => p.text ?? "");
+    return texts.join("\n").trim();
+}
+/**
+ * Parse a "provider/model" string into its components.
+ * Returns undefined if the input is empty or doesn't contain a "/".
+ *
+ * Examples:
+ *   "azure/gpt-5.2-chat"          → { provider: "azure", model: "gpt-5.2-chat" }
+ *   "custom-host/org/model-v2"    → { provider: "custom-host", model: "org/model-v2" }
+ *   ""                            → undefined
+ *   "bare-model-name"             → undefined (no "/" — may be an alias)
+ */
+export function parseModelRef(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const slashIdx = trimmed.indexOf("/");
+    if (slashIdx <= 0 || slashIdx === trimmed.length - 1)
+        return undefined;
+    return {
+        provider: trimmed.slice(0, slashIdx),
+        model: trimmed.slice(slashIdx + 1),
+    };
+}
+/**
+ * Resolve the user's default model from the main OpenClaw config.
+ *
+ * Resolution order:
+ * 1. Read `agents.defaults.model` (string or { primary })
+ * 2. If the value contains "/", parse directly
+ * 3. If not (may be an alias), look up in `agents.defaults.models` alias table
+ * 4. Return undefined if nothing resolves — let the core use its built-in default
+ */
+export function resolveModelFromMainConfig(config) {
+    if (!config || typeof config !== "object")
+        return undefined;
+    const cfg = config;
+    const agents = cfg.agents;
+    if (!agents || typeof agents !== "object")
+        return undefined;
+    const defaults = agents.defaults;
+    if (!defaults || typeof defaults !== "object")
+        return undefined;
+    // Step 1: extract raw model value (string | { primary?: string })
+    const modelCfg = defaults.model;
+    let raw;
+    if (typeof modelCfg === "string") {
+        raw = modelCfg.trim();
+    }
+    else if (modelCfg && typeof modelCfg === "object") {
+        const primary = modelCfg.primary;
+        raw = typeof primary === "string" ? primary.trim() : undefined;
+    }
+    if (!raw)
+        return undefined;
+    // Step 2: try direct "provider/model" parse
+    const direct = parseModelRef(raw);
+    if (direct)
+        return direct;
+    // Step 3: alias lookup — raw doesn't contain "/", check agents.defaults.models
+    const models = defaults.models;
+    if (!models || typeof models !== "object")
+        return undefined;
+    const rawLower = raw.toLowerCase();
+    for (const [key, entry] of Object.entries(models)) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const alias = entry.alias;
+        if (typeof alias !== "string")
+            continue;
+        if (alias.trim().toLowerCase() !== rawLower)
+            continue;
+        // key is "provider/model" format
+        const resolved = parseModelRef(key);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}
+// Stable empty directory used as default workspaceDir so that:
+// 1. Bootstrap/skills scans find nothing → clean LLM context
+// 2. The path is constant → plugin cacheKey stays stable (no re-registration)
+let _cleanWorkspaceDir;
+async function getCleanWorkspaceDir() {
+    if (_cleanWorkspaceDir)
+        return _cleanWorkspaceDir;
+    const dir = path.join(resolveOpenClawTmpDir(), "memory-tdai-clean-workspace");
+    await fs.mkdir(dir, { recursive: true });
+    _cleanWorkspaceDir = dir;
+    return dir;
+}
+export class CleanContextRunner {
+    options;
+    logger;
+    /** Resolved provider after modelRef / config fallback */
+    resolvedProvider;
+    /** Resolved model after modelRef / config fallback */
+    resolvedModel;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger;
+        // Model resolution priority:
+        // 1. modelRef ("provider/model" string)  — highest
+        // 2. explicit provider + model fields
+        // 3. main config agents.defaults.model   — automatic fallback
+        // 4. undefined (let core use built-in default)
+        const fromRef = parseModelRef(options.modelRef);
+        if (fromRef) {
+            this.resolvedProvider = fromRef.provider;
+            this.resolvedModel = fromRef.model;
+        }
+        else if (options.provider || options.model) {
+            this.resolvedProvider = options.provider;
+            this.resolvedModel = options.model;
+        }
+        else {
+            // No explicit model specified — fall back to main config
+            const fromConfig = resolveModelFromMainConfig(options.config);
+            if (fromConfig) {
+                this.resolvedProvider = fromConfig.provider;
+                this.resolvedModel = fromConfig.model;
+                this.logger?.debug?.(`${TAG} Using model from main config: ${fromConfig.provider}/${fromConfig.model}`);
+            }
+            // else: both undefined → core will use its built-in default (anthropic/claude-opus-4-6)
+        }
+    }
+    /**
+     * Run a prompt in a fully isolated clean context.
+     * Returns the LLM's text output.
+     *
+     * When `workspaceDir` is provided it overrides the default `process.cwd()`,
+     * letting the LLM's file-tool calls resolve paths relative to a custom root.
+     */
+    async run(params) {
+        const runStartMs = Date.now();
+        this.logger?.debug?.(`${TAG} run() start: taskId=${params.taskId}, timeout=${params.timeoutMs ?? 120_000}ms, tools=${this.options.enableTools ? "enabled" : "disabled"}, workspaceDir=${params.workspaceDir ?? "(default)"}`);
+        const tmpDir = await fs.mkdtemp(path.join(resolveOpenClawTmpDir(), `memory-tdai-${params.taskId}-`));
+        const cleanWorkspace = params.workspaceDir ?? await getCleanWorkspaceDir();
+        this.logger?.debug?.(`${TAG} run() tmpDir=${tmpDir}, cleanWorkspace=${cleanWorkspace}`);
+        try {
+            const sessionFile = path.join(tmpDir, "session.json");
+            // Phase 1: Resolve runEmbeddedPiAgent (prefer runtime, fallback to legacy dist bridge)
+            const importStartMs = Date.now();
+            const runEmbeddedPiAgent = await resolveRunEmbeddedPiAgent(this.options.agentRuntime, this.logger);
+            const importElapsedMs = Date.now() - importStartMs;
+            this.logger?.debug?.(`${TAG} run() runner resolution phase: ${importElapsedMs}ms`);
+            // Derive a config with plugins disabled to prevent loadOpenClawPlugins
+            // from re-registering plugins when the workspaceDir differs from the
+            // gateway's original workspace (cacheKey mismatch triggers full reload).
+            //
+            // Security: restrict available tools to the minimal set needed for
+            // scene extraction (read/write/edit). This prevents the LLM from
+            // accessing exec, sessions, browser, cron, or any other powerful tools.
+            // File deletion is handled via "soft-delete" (write empty) + cleanup afterward.
+            const cleanConfig = {
+                ...this.options.config,
+                plugins: {
+                    ...this.options.config?.plugins,
+                    enabled: false,
+                },
+                tools: {
+                    ...this.options.config?.tools,
+                    // When enableTools=true, restrict to the minimal set needed for
+                    // scene extraction (read/write/edit).
+                    // When enableTools=false, pass an empty allow list — disableTools:true
+                    // will prevent tools from being sent to the API entirely.
+                    allow: this.options.enableTools ? ["read", "write", "edit"] : [],
+                },
+                // Override the full agent system prompt with the caller's extraction-specific
+                // system prompt. This replaces OpenClaw's default system prompt (identity,
+                // AGENTS.md, workspace context, tool guidance, etc.) to:
+                //   1. Save ~5000 tokens per LLM call
+                //   2. Avoid instruction interference with extraction prompts
+                agents: {
+                    ...this.options.config?.agents,
+                    defaults: {
+                        ...this.options.config?.agents?.defaults,
+                        systemPromptOverride: params.systemPrompt ||
+                            "You are a precise data extraction and generation assistant. Follow the user instructions exactly. Respond only with the requested output format.",
+                    },
+                },
+            };
+            // systemPrompt is now in config.agents.defaults.systemPromptOverride
+            // (actual [system] role), so user prompt only contains the actual content.
+            const effectivePrompt = params.prompt;
+            const ts = Date.now();
+            const sessionId = `memory-${params.taskId}-session-${ts}`;
+            const runId = `memory-${params.taskId}-run-${ts}`;
+            this.logger?.debug?.(`${TAG} run() starting embedded agent: sessionId=${sessionId}, runId=${runId}, provider=${this.resolvedProvider ?? "(default)"}, model=${this.resolvedModel ?? "(default)"}`);
+            // [l1-debug] INVOKE — what are we about to send to the embedded agent?
+            const sysPromptOverrideLen = cleanConfig.agents?.defaults?.systemPromptOverride
+                ? String(cleanConfig.agents.defaults.systemPromptOverride).length
+                : 0;
+            const toolsAllow = cleanConfig.tools?.allow ?? [];
+            this.logger?.debug?.(`${TAG} [l1-debug] INVOKE taskId=${params.taskId}, provider=${this.resolvedProvider ?? "(default)"}, model=${this.resolvedModel ?? "(default)"}, promptLen=${effectivePrompt.length}, sysPromptOverrideLen=${sysPromptOverrideLen}, toolsAllow=${JSON.stringify(toolsAllow)}, timeoutMs=${params.timeoutMs ?? 120_000}`);
+            // Phase 2: Embedded agent run (LLM call + tool calls)
+            const agentStartMs = Date.now();
+            // extraSystemPrompt: fallback for openclaw < 2026.4.7 which does not support
+            // config.agents.defaults.systemPromptOverride. On newer versions the
+            // override takes precedence and this becomes a no-op append.
+            const effectiveSystemPrompt = params.systemPrompt ||
+                "You are a precise data extraction and generation assistant. Follow the user instructions exactly. Respond only with the requested output format.";
+            const result = await runEmbeddedPiAgent({
+                sessionId,
+                sessionFile,
+                workspaceDir: cleanWorkspace,
+                config: cleanConfig,
+                prompt: effectivePrompt,
+                timeoutMs: params.timeoutMs ?? 120_000,
+                runId,
+                provider: this.resolvedProvider,
+                model: this.resolvedModel,
+                // When enableTools=false, pass disableTools:true so that no tool
+                // definitions are sent to the API. This avoids polluting the LLM
+                // context with tool schemas and prevents the model from attempting
+                // tool calls during pure text extraction tasks.
+                // If a provider (e.g. qwencode) rejects empty tools[], users should
+                // switch to StandaloneLLMRunner via LLM configuration instead.
+                disableTools: !this.options.enableTools,
+                extraSystemPrompt: effectiveSystemPrompt,
+                streamParams: {
+                    maxTokens: params.maxTokens,
+                },
+            });
+            const agentElapsedMs = Date.now() - agentStartMs;
+            this.logger?.debug?.(`${TAG} run() embedded agent completed: ${agentElapsedMs}ms`);
+            // [l1-debug] RESULT — what did the embedded agent return?
+            {
+                const payloadsRaw = result?.payloads;
+                const payloads = Array.isArray(payloadsRaw)
+                    ? payloadsRaw
+                    : [];
+                const payloadKinds = payloads.map((p) => {
+                    if (typeof p?.type === "string")
+                        return p.type;
+                    if (typeof p?.kind === "string")
+                        return p.kind;
+                    return Object.keys(p ?? {}).slice(0, 3).join("|") || "unknown";
+                });
+                const errorPayloadCount = payloads.filter((p) => p?.isError === true).length;
+                const joinedText = payloads
+                    .filter((p) => !p?.isError && typeof p?.text === "string")
+                    .map((p) => String(p.text ?? ""))
+                    .join("\n");
+                const textPreview = joinedText.replace(/\s+/g, " ").slice(0, 200);
+                this.logger?.debug?.(`${TAG} [l1-debug] RESULT taskId=${params.taskId}, elapsedMs=${agentElapsedMs}, payloadCount=${payloads.length}, payloadKinds=${JSON.stringify(payloadKinds)}, errorPayloadCount=${errorPayloadCount}, textLen=${joinedText.length}, textPreview=${JSON.stringify(textPreview)}`);
+            }
+            // Phase 3: Collect output
+            const text = collectText(result.payloads);
+            const totalMs = Date.now() - runStartMs;
+            if (!text) {
+                // Empty output is normal when the LLM decides there is nothing to
+                // extract (e.g. trivial greetings).  Log a warning instead of
+                // throwing so the caller can handle it gracefully.
+                this.logger?.warn?.(`${TAG} run() empty output after ${totalMs}ms (import=${importElapsedMs}ms, agent=${agentElapsedMs}ms) — treating as empty result`);
+                // [l1-debug] EMPTY_DUMP — dump the full result shape so we can see where text went
+                try {
+                    const dump = JSON.stringify(result, (_k, v) => {
+                        if (typeof v === "string" && v.length > 500)
+                            return v.slice(0, 500) + `…(+${v.length - 500})`;
+                        return v;
+                    }).slice(0, 2048);
+                    this.logger?.warn?.(`${TAG} [l1-debug] EMPTY_DUMP taskId=${params.taskId}, resultJson=${dump}`);
+                }
+                catch (dumpErr) {
+                    this.logger?.warn?.(`${TAG} [l1-debug] EMPTY_DUMP taskId=${params.taskId}, dumpFailed=${dumpErr instanceof Error ? dumpErr.message : String(dumpErr)}`);
+                }
+                // llm_call metric (empty output)
+                if (params.instanceId && this.logger) {
+                    report("llm_call", {
+                        taskId: params.taskId,
+                        provider: this.resolvedProvider ?? "default",
+                        model: this.resolvedModel ?? "default",
+                        inputLength: params.prompt.length,
+                        outputLength: 0,
+                        totalDurationMs: totalMs,
+                        success: true,
+                        error: "empty_output",
+                    });
+                }
+                return "";
+            }
+            this.logger?.debug?.(`${TAG} run() completed: ${totalMs}ms total (import=${importElapsedMs}ms, agent=${agentElapsedMs}ms), output=${text.length} chars`);
+            // ── llm_call metric (success) ──
+            if (params.instanceId && this.logger) {
+                report("llm_call", {
+                    taskId: params.taskId,
+                    provider: this.resolvedProvider ?? "default",
+                    model: this.resolvedModel ?? "default",
+                    inputLength: params.prompt.length,
+                    outputLength: text.length,
+                    totalDurationMs: totalMs,
+                    success: true,
+                    error: null,
+                });
+            }
+            return text;
+        }
+        catch (err) {
+            const totalMs = Date.now() - runStartMs;
+            this.logger?.error(`${TAG} run() failed after ${totalMs}ms: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+            // ── llm_call metric (failure) ──
+            if (params.instanceId && this.logger) {
+                report("llm_call", {
+                    taskId: params.taskId,
+                    provider: this.resolvedProvider ?? "default",
+                    model: this.resolvedModel ?? "default",
+                    inputLength: params.prompt.length,
+                    outputLength: 0,
+                    totalDurationMs: totalMs,
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            throw err;
+        }
+        finally {
+            await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/vendor/tdai/utils/ensure-hook-policy.js

@@ -0,0 +1,213 @@
+/**
+ * ensure-hook-policy.ts
+ *
+ * Auto-patches openclaw.json to add `hooks.allowConversationAccess: true`
+ * for our plugin. Without it, the gateway silently blocks agent_end hooks
+ * for non-bundled plugins (v2026.4.23+, PR #70786).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getEnv } from "./env.js";
+import JSON5 from "json5";
+const PLUGIN_ID = "memory-tencentdb";
+/**
+ * Minimum host version at which `hooks.allowConversationAccess` is both
+ * recognised by the schema and enforced. See header comment.
+ */
+export const HOOK_POLICY_MIN_VERSION = [
+    2026, 4, 24,
+];
+/**
+ * Parse the leading `x.y.z` numeric prefix from a version string.
+ *
+ * Accepts:
+ *   "2026.4.24"          -> [2026, 4, 24]
+ *   "2026.4.24-beta.1"   -> [2026, 4, 24]
+ *   "2026.5.3-1"         -> [2026, 5,  3]
+ *   "2026.4.24.4"        -> [2026, 4, 24]   (extra segments ignored)
+ *
+ * Rejects (returns null):
+ *   - Non-string values  (undefined / null / number / etc.)
+ *   - "unknown" / ""     (no clean numeric prefix)
+ *   - "2026.4"           (must have all three segments)
+ *   - "v2026.4.24"       (no leading non-digit allowed — keep strict)
+ */
+export function parseVersionXYZ(v) {
+    if (typeof v !== "string") {
+        return null;
+    }
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)(?:[-.].*)?$/);
+    if (!m) {
+        return null;
+    }
+    const [, a, b, c] = m;
+    return [Number(a), Number(b), Number(c)];
+}
+/**
+ * Compare two `[x, y, z]` tuples. Returns negative / 0 / positive like a
+ * standard comparator (a - b).
+ */
+export function compareVersionXYZ(a, b) {
+    return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+/**
+ * Decide whether we should apply the `allowConversationAccess` auto-patch
+ * for the given host version, returning a structured result that callers
+ * can log verbatim.
+ *
+ * Policy:
+ *   - Extract the leading `x.y.z` prefix from `rawVersion` (ignoring any
+ *     pre-release suffix like `-beta.N`, `-1`, `-alpha.N`, etc.).
+ *   - If the prefix is >= {@link HOOK_POLICY_MIN_VERSION}, `apply = true`.
+ *   - If the prefix cannot be parsed (unknown / empty / non-string /
+ *     undefined — typical on hosts that don't expose `api.runtime.version`),
+ *     `apply = false`.  This is the safe default: old hosts don't have the
+ *     gate and don't need patching.
+ *
+ * NOTE: Very early pre-releases of the MIN version itself (e.g.
+ * `2026.4.24-beta.1`) will satisfy the predicate. This is intentional —
+ * the field was already recognised in those builds and the usage base is
+ * negligible.
+ */
+export function decideHookPolicy(rawVersion) {
+    const parsedXYZ = parseVersionXYZ(rawVersion);
+    const apply = parsedXYZ !== null &&
+        compareVersionXYZ(parsedXYZ, HOOK_POLICY_MIN_VERSION) >= 0;
+    return {
+        apply,
+        rawVersion,
+        parsedXYZ,
+        minXYZ: HOOK_POLICY_MIN_VERSION,
+    };
+}
+/**
+ * Thin boolean wrapper around {@link decideHookPolicy} for callers that
+ * only need the yes/no answer.
+ */
+export function shouldApplyHookPolicy(rawVersion) {
+    return decideHookPolicy(rawVersion).apply;
+}
+function isObj(v) {
+    return v != null && typeof v === "object" && !Array.isArray(v);
+}
+function isGatewayStart() {
+    const args = process.argv.map((v) => String(v || "").toLowerCase());
+    const idx = args.findIndex((a) => a.endsWith("openclaw") || a.endsWith("openclaw.mjs") || a.endsWith("entry.js"));
+    if (idx < 0)
+        return true;
+    const cmd = args.slice(idx + 1).filter((a) => !a.startsWith("-"))[0];
+    if (!cmd)
+        return true;
+    const skip = ["plugins", "plugin", "install", "uninstall", "update", "doctor", "security", "config", "onboard", "setup", "status", "version", "help"];
+    return !skip.includes(cmd);
+}
+function resolveConfigPath() {
+    // 1. OPENCLAW_CONFIG_PATH env override (same as core uses)
+    const envPath = getEnv("OPENCLAW_CONFIG_PATH")?.trim();
+    if (envPath && fs.existsSync(envPath))
+        return envPath;
+    // 2. OPENCLAW_STATE_DIR override
+    const stateDir = getEnv("OPENCLAW_STATE_DIR")?.trim();
+    if (stateDir) {
+        const p = path.join(stateDir, "openclaw.json");
+        if (fs.existsSync(p))
+            return p;
+    }
+    // 3. Standard location: ~/.openclaw/openclaw.json
+    const home = getEnv("HOME") ?? getEnv("USERPROFILE") ?? "";
+    if (!home)
+        return null;
+    const p = path.join(home, ".openclaw", "openclaw.json");
+    return fs.existsSync(p) ? p : null;
+}
+function hasPolicyAlready(root) {
+    if (!isObj(root))
+        return false;
+    const entry = root?.plugins?.entries?.[PLUGIN_ID];
+    return isObj(entry) && isObj(entry.hooks) && entry.hooks.allowConversationAccess === true;
+}
+/**
+ * Call early in register(). Patches config if missing, triggers restart.
+ *
+ * Strategy:
+ * 1. Try SDK mutateConfigFile (handles path resolution, $include, atomic write,
+ *    and triggers gateway restart via afterWrite).
+ * 2. Fallback to manual file write if SDK is unavailable or fails.
+ */
+export function ensurePluginHookPolicy(params) {
+    const { logger } = params;
+    const TAG = "[memory-tdai] [hook-policy]";
+    if (!isGatewayStart())
+        return;
+    if (hasPolicyAlready(params.rootConfig))
+        return;
+    // Try SDK path first (handles everything + triggers restart)
+    if (params.runtimeConfig?.mutateConfigFile) {
+        logger.info(`${TAG} Missing allowConversationAccess, patching via SDK...`);
+        params.runtimeConfig.mutateConfigFile({
+            afterWrite: { mode: "restart", reason: "memory-tencentdb hook policy auto-patch" },
+            mutate: (draft) => {
+                if (!draft.plugins)
+                    draft.plugins = {};
+                if (!draft.plugins.entries)
+                    draft.plugins.entries = {};
+                if (!draft.plugins.entries[PLUGIN_ID])
+                    draft.plugins.entries[PLUGIN_ID] = {};
+                if (!draft.plugins.entries[PLUGIN_ID].hooks)
+                    draft.plugins.entries[PLUGIN_ID].hooks = {};
+                draft.plugins.entries[PLUGIN_ID].hooks.allowConversationAccess = true;
+            },
+        }).then(() => {
+            logger.info(`${TAG} ✅ Patched via SDK — gateway will restart automatically.`);
+        }).catch((err) => {
+            logger.warn(`${TAG} SDK mutateConfigFile failed: ${err instanceof Error ? err.message : String(err)}, trying manual fallback...`);
+            manualPatch(logger);
+        });
+        return;
+    }
+    // Fallback: manual file write
+    manualPatch(logger);
+}
+function manualPatch(logger) {
+    const TAG = "[memory-tdai] [hook-policy]";
+    const configPath = resolveConfigPath();
+    if (!configPath) {
+        logger.warn(`${TAG} Cannot locate openclaw.json — please add hooks.allowConversationAccess manually`);
+        return;
+    }
+    let parsed;
+    try {
+        const raw = fs.readFileSync(configPath, "utf-8");
+        parsed = JSON5.parse(raw);
+    }
+    catch {
+        logger.warn(`${TAG} Failed to parse ${configPath} — please add hooks.allowConversationAccess manually`);
+        return;
+    }
+    if (hasPolicyAlready(parsed))
+        return;
+    if ("$include" in parsed || (isObj(parsed.plugins) && "$include" in parsed.plugins)) {
+        logger.warn(`${TAG} Config uses $include — please add manually: plugins.entries.${PLUGIN_ID}.hooks.allowConversationAccess = true`);
+        return;
+    }
+    if (!isObj(parsed.plugins))
+        parsed.plugins = {};
+    const plugins = parsed.plugins;
+    if (!isObj(plugins.entries))
+        plugins.entries = {};
+    const entries = plugins.entries;
+    if (!isObj(entries[PLUGIN_ID]))
+        entries[PLUGIN_ID] = {};
+    const entry = entries[PLUGIN_ID];
+    if (!isObj(entry.hooks))
+        entry.hooks = {};
+    entry.hooks.allowConversationAccess = true;
+    try {
+        fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2) + "\n");
+        logger.info(`${TAG} ✅ Auto-added hooks.allowConversationAccess to ${configPath}`);
+        logger.warn(`${TAG} ⚠️  Gateway restart required. Run: openclaw gateway restart`);
+    }
+    catch (err) {
+        logger.warn(`${TAG} Failed to write ${configPath}: ${err instanceof Error ? err.message : String(err)}. Add manually.`);
+    }
+}