anolisa-tokenless 0.7.7

package/adapters/tokenless/openclaw/dist/index.js

@@ -0,0 +1,598 @@
+/**
+ * Token-Less Unified Plugin for OpenClaw v5
+ *
+ * Combines multiple complementary optimisation strategies into a single plugin:
+ *
+ *   1. RTK command rewriting  — transparently rewrites exec tool commands to
+ *      their RTK equivalents (delegated to `rtk rewrite`).
+ *   2. Tokenless response compression — compresses tool responses via
+ *      `tokenless compress-response` (removes debug/null/empty values).
+ *   3. TOON context compression — encodes JSON tool responses to TOON format
+ *      via `tokenless compress-toon`, reducing token usage for structured data. When both
+ *      response and TOON compression are enabled, they run sequentially:
+ *      Response Compression strips noise → TOON eliminates JSON format overhead.
+ *
+ * Stats are recorded automatically by tokenless compress-response.
+ * RTK rewrite and proxy processes receive the same per-call context snapshot;
+ * the rewrite-context file remains a compatibility fallback for launch paths
+ * that do not preserve exec environment overrides.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+// ---- Session ID mapping --------------------------------------------------------
+// OpenClaw's tool_result_persist ctx provides sessionKey ("agent:main:main")
+// but NOT sessionId (UUID). We maintain a sessionKey → sessionId map built
+// from session_start events so response compression can use the correct UUID.
+const sessionMap = new Map();
+const envContext = {
+    agentId: "openclaw", sessionId: "", toolCallId: "",
+};
+function buildEnv(context = envContext) {
+    return {
+        ...process.env,
+        ...buildContextEnv(context),
+    };
+}
+function buildContextEnv(context) {
+    return {
+        TOKENLESS_AGENT_ID: context.agentId,
+        TOKENLESS_SESSION_ID: context.sessionId,
+        TOKENLESS_TOOL_USE_ID: context.toolCallId,
+    };
+}
+function mergeExecContextEnv(params, context) {
+    const existingEnv = params.env;
+    const normalizedEnv = typeof existingEnv === "object"
+        && existingEnv !== null
+        && !Array.isArray(existingEnv)
+        ? existingEnv
+        : {};
+    return {
+        ...normalizedEnv,
+        ...buildContextEnv(context),
+    };
+}
+// ---- Binary availability cache (with TTL for negative results) -----------------
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes — retry after auto-fix installs
+let rtkAvailable = null;
+let rtkCheckedAt = null;
+let tokenlessAvailable = null;
+let tokenlessCheckedAt = null;
+// Resolved absolute paths — set by check*() functions so subprocess calls
+// use the correct path even when the binary is not on PATH.
+let rtkPath = "rtk";
+let tokenlessPath = "tokenless";
+// KEEP IN SYNC with common/hooks/hook_utils.py, tool_ready_hook.sh,
+// env_check.rs::binary_fallback_paths, and the Codex standalone scripts.
+// Makefile and the Anolisa component manifest define the supported layouts;
+// the canonical order is user, /usr/local, /usr, then legacy.
+const LIBEXEC_FALLBACK = "/usr/libexec/anolisa/tokenless";
+const LIB_FALLBACK = "/usr/lib/anolisa/tokenless";
+const TOKENLESS_FALLBACK = "/usr/bin/tokenless";
+const SYSTEM_BIN = "/usr/local/bin";
+const SYSTEM_LIBEXEC = "/usr/local/libexec/anolisa/tokenless";
+const RPM_BIN = "/usr/bin";
+const USER_HOME = process.env.HOME && isAbsolute(process.env.HOME) ? process.env.HOME : null;
+const REWRITE_CONTEXT_DIR = USER_HOME ? join(USER_HOME, ".tokenless") : null;
+const REWRITE_CONTEXT_FILE = REWRITE_CONTEXT_DIR
+    ? join(REWRITE_CONTEXT_DIR, ".rewrite-context")
+    : null;
+const LOCAL_BIN = USER_HOME ? join(USER_HOME, ".local", "bin") : null;
+const LOCAL_ANOLISA_LIBEXEC = USER_HOME
+    ? join(USER_HOME, ".local", "lib", "anolisa", "libexec", "tokenless")
+    : null;
+const LOCAL_MAKE_LIBEXEC = USER_HOME
+    ? join(USER_HOME, ".local", "libexec", "anolisa", "tokenless")
+    : null;
+const LOCAL_LIB = USER_HOME
+    ? join(USER_HOME, ".local", "lib", "anolisa", "tokenless")
+    : null;
+const LOCAL_FALLBACK = USER_HOME
+    ? join(USER_HOME, ".local", "share", "anolisa", "tokenless")
+    : null;
+function binaryIn(directory, name) {
+    return directory ? join(directory, name) : "";
+}
+// Check both existence and execute permission (mirrors shell `-x` test).
+function isExecutable(path) {
+    try {
+        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveBinaryPath(name, ...fallbacks) {
+    // Search PATH directories without spawning a shell (mirrors headroom
+    // and agent-memory plugins).  Avoids `sh -c "command -v"` so the
+    // only child_process calls are direct binary invocations with fixed
+    // paths — no shell interpolation vector exists.
+    const pathEnv = process.env.PATH || "";
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        if (existsSync(candidate) && isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    // Fall back to known locations.
+    for (const fb of fallbacks) {
+        if (fb && isExecutable(fb))
+            return fb;
+    }
+    return null;
+}
+function checkRtk() {
+    // Refresh BOTH true and false cache once stale: a binary that was
+    // present at first check can disappear (manual uninstall, FS error,
+    // overlay swap) and a previously-missing binary can be installed by
+    // auto-fix. Asymmetric TTL would either keep using a vanished path
+    // (stale true) or never re-check after install (stale false).
+    if (rtkAvailable !== null && rtkCheckedAt && (Date.now() - rtkCheckedAt > CACHE_TTL_MS)) {
+        rtkAvailable = null;
+    }
+    if (rtkAvailable !== null)
+        return rtkAvailable;
+    const resolved = resolveBinaryPath("rtk", binaryIn(LOCAL_BIN, "rtk"), binaryIn(LOCAL_ANOLISA_LIBEXEC, "rtk"), binaryIn(LOCAL_MAKE_LIBEXEC, "rtk"), join(SYSTEM_BIN, "rtk"), join(SYSTEM_LIBEXEC, "rtk"), join(RPM_BIN, "rtk"), join(LIBEXEC_FALLBACK, "rtk"), join(LIB_FALLBACK, "rtk"), binaryIn(LOCAL_FALLBACK, "rtk"), binaryIn(LOCAL_LIB, "rtk"));
+    if (resolved) {
+        rtkPath = resolved;
+        rtkAvailable = true;
+    }
+    else {
+        rtkAvailable = false;
+    }
+    rtkCheckedAt = Date.now();
+    return rtkAvailable;
+}
+function isSkillContent(message) {
+    // Skill files (.md with YAML frontmatter) must not be compressed because
+    // truncation would break the skill metadata and make agent skills unusable.
+    if (typeof message !== "string")
+        return false;
+    const trimmed = message.trimStart();
+    if (!trimmed.startsWith("---"))
+        return false;
+    // Check the first few lines for typical skill metadata fields
+    const firstLines = trimmed.split("\n", 20).join("\n");
+    return /^name:/m.test(firstLines) || /^description:/m.test(firstLines);
+}
+function checkTokenless() {
+    // Refresh BOTH true and false cache once stale (see checkRtk for rationale).
+    if (tokenlessAvailable !== null && tokenlessCheckedAt && (Date.now() - tokenlessCheckedAt > CACHE_TTL_MS)) {
+        tokenlessAvailable = null;
+    }
+    if (tokenlessAvailable !== null)
+        return tokenlessAvailable;
+    const resolved = resolveBinaryPath("tokenless", binaryIn(LOCAL_BIN, "tokenless"), join(SYSTEM_BIN, "tokenless"), TOKENLESS_FALLBACK, binaryIn(LOCAL_FALLBACK, "tokenless"), binaryIn(LOCAL_LIB, "tokenless"));
+    if (resolved) {
+        tokenlessPath = resolved;
+        tokenlessAvailable = true;
+    }
+    else {
+        tokenlessAvailable = false;
+    }
+    tokenlessCheckedAt = Date.now();
+    return tokenlessAvailable;
+}
+// ---- Subprocess helpers -------------------------------------------------------
+function tryRtkRewrite(command, context) {
+    try {
+        const result = spawnSync(rtkPath, ["rewrite", command], {
+            encoding: "utf-8",
+            timeout: 2000,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: buildEnv(context),
+        });
+        const rewritten = result.stdout?.trim();
+        // Exit code protocol (from rtk rewrite_cmd.rs):
+        //   0 = rewrite available, Allow verdict (auto-allow by permission rule)
+        //   1 = no RTK equivalent (passthrough)
+        //   2 = deny rule matched (let agent handle)
+        //   3 = Ask/Default verdict (rewrite available but permission model requires
+        //       user confirmation; in non-interactive hook context, treat as valid
+        //       rewrite since the intent is token optimization, not permission gating)
+        if ((result.status === 0 || result.status === 3) && rewritten && rewritten !== command) {
+            return rewritten;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeRewriteContext(context) {
+    if (!REWRITE_CONTEXT_DIR || !REWRITE_CONTEXT_FILE) {
+        console.warn("[tokenless:rtk] cannot persist rewrite context: HOME is unavailable");
+        return;
+    }
+    let fd = null;
+    try {
+        mkdirSync(REWRITE_CONTEXT_DIR, { recursive: true, mode: 0o700 });
+        // O_NOFOLLOW protects only the final component, so reject a symlinked parent.
+        if (!lstatSync(REWRITE_CONTEXT_DIR).isDirectory()) {
+            throw new Error(`rewrite context directory is not a directory: ${REWRITE_CONTEXT_DIR}`);
+        }
+        fd = openSync(REWRITE_CONTEXT_FILE, constants.O_WRONLY
+            | constants.O_CREAT
+            | constants.O_TRUNC
+            | constants.O_NOFOLLOW, 0o600);
+        // The open mode protects new files; fchmod also tightens an existing file.
+        fchmodSync(fd, 0o600);
+        writeFileSync(fd, `${context.agentId}\n${context.sessionId}\n${context.toolCallId}\n`, "utf-8");
+    }
+    catch (error) {
+        const code = error?.code;
+        const suffix = code ? ` (${code})` : "";
+        console.warn(`[tokenless:rtk] cannot persist rewrite context${suffix}`);
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // The rewrite must proceed even if closing the fail-soft stats context fails.
+            }
+        }
+    }
+}
+function tryCompressResponse(response, sessionId, toolCallId, thresholds) {
+    try {
+        const input = JSON.stringify(response);
+        // 3-layer dispatch: thresholds vary by tool category.
+        //   Shell/exec tools: moderate truncation (64K/128/8) — preserves 95% of real output
+        //   API/structured tools: zero-truncation (1M/64K/32) — preserve content
+        const [truncateStringsAt, truncateArraysAt, maxDepth] = thresholds ?? [1048576, 65536, 32];
+        const args = [
+            "compress-response", "--agent-id", "openclaw",
+            "--truncate-strings-at", String(truncateStringsAt),
+            "--truncate-arrays-at", String(truncateArraysAt),
+            "--max-depth", String(maxDepth),
+        ];
+        if (sessionId)
+            args.push("--session-id", sessionId);
+        if (toolCallId)
+            args.push("--tool-use-id", toolCallId);
+        const result = execFileSync(tokenlessPath, args, {
+            encoding: "utf-8",
+            timeout: 3000,
+            input,
+            env: buildEnv(),
+        }).trim();
+        // Only return the compressed result if it is shorter than the input
+        if (result.length >= input.length) {
+            return null; // No actual compression occurred
+        }
+        return JSON.parse(result);
+    }
+    catch {
+        return null;
+    }
+}
+function tryCompressToon(response, sessionId, toolCallId) {
+    try {
+        const input = JSON.stringify(response);
+        const beforeChars = input.length;
+        const args = ["compress-toon", "--agent-id", "openclaw"];
+        if (sessionId)
+            args.push("--session-id", sessionId);
+        if (toolCallId)
+            args.push("--tool-use-id", toolCallId);
+        const toonText = execFileSync(tokenlessPath, args, {
+            encoding: "utf-8",
+            timeout: 1000,
+            input,
+            env: buildEnv(),
+        }).trim();
+        if (!toonText || toonText.length >= beforeChars)
+            return null;
+        const afterChars = toonText.length;
+        const savingsPct = beforeChars > 0 ? Math.round(((beforeChars - afterChars) / beforeChars) * 100) : 0;
+        return { toonText, savingsPct };
+    }
+    catch {
+        return null;
+    }
+}
+function tryEnvCheck(toolName) {
+    try {
+        const result = execFileSync(tokenlessPath, ["env-check", "--tool", toolName, "--json"], {
+            encoding: "utf-8",
+            timeout: 3000,
+            env: buildEnv(),
+        }).trim();
+        const parsed = JSON.parse(result);
+        const status = parsed.status || "UNKNOWN";
+        // Phase 1+2: UNKNOWN (not in dict) or READY → skip silently
+        if (status === "UNKNOWN" || status === "READY")
+            return null;
+        // Phase 3: NOT_READY → attempt auto-fix
+        const fixResult = execFileSync(tokenlessPath, ["env-check", "--tool", toolName, "--fix", "--json"], {
+            encoding: "utf-8",
+            timeout: 10000,
+            env: buildEnv(),
+        }).trim();
+        const fixParsed = JSON.parse(fixResult);
+        const postStatus = fixParsed.status || "NOT_READY";
+        // Phase 3 success: fix worked → continue silently
+        if (postStatus === "READY")
+            return null;
+        // Phase 4: Fix failed → feedback to Agent
+        const diagnostic = fixParsed.diagnostic
+            || `[tokenless:ready] ${toolName}: NOT_READY. Skip retry.`;
+        return { status: postStatus, diagnostic };
+    }
+    catch {
+        return null;
+    }
+}
+// Hardcoded fallback tool sets — used only when tool_categories.json is missing
+// or invalid. Mirrors Python hook_utils._FALLBACK_SKIP_TOOLS/_FALLBACK_SHELL_TOOLS
+// to ensure consistent behavior across adapters even without the JSON file.
+const FALLBACK_SKIP_TOOLS = [
+    "Read", "read", "read_file", "read_many_files",
+    "Glob", "glob", "search_file", "list_directory", "list_dir",
+    "Grep", "grep", "grep_code", "grep_search", "search_files",
+    "Lsp", "lsp",
+    "NotebookRead", "notebook_read", "notebookread",
+];
+const FALLBACK_SHELL_TOOLS = [
+    "Bash", "bash", "Shell", "shell", "exec", "terminal",
+    "run_shell_command", "run_in_terminal", "get_terminal_output",
+    "execute_command", "process",
+];
+function loadToolCategories() {
+    const fallback = {
+        layer_1_skip: { tools: FALLBACK_SKIP_TOOLS },
+        layer_2_shell: { tools: FALLBACK_SHELL_TOOLS },
+        layer_3_api: {},
+    };
+    try {
+        // Try multiple possible locations for tool_categories.json
+        const possiblePaths = [
+            join(import.meta.dirname, "tool_categories.json"),
+            join(import.meta.dirname, "..", "..", "common", "hooks", "tool_categories.json"),
+            join(import.meta.dirname, "common", "hooks", "tool_categories.json"),
+            "/usr/share/anolisa/adapters/tokenless/common/hooks/tool_categories.json",
+            "/usr/local/share/anolisa/adapters/tokenless/common/hooks/tool_categories.json",
+        ];
+        let content = null;
+        for (const path of possiblePaths) {
+            if (existsSync(path)) {
+                content = readFileSync(path, "utf-8");
+                break;
+            }
+        }
+        if (!content) {
+            console.warn("[tokenless] Could not find tool_categories.json, using hardcoded fallback categories");
+            return fallback;
+        }
+        const data = JSON.parse(content);
+        // Validate required structure
+        const requiredLayers = ["layer_1_skip", "layer_2_shell", "layer_3_api"];
+        for (const layer of requiredLayers) {
+            if (!(layer in data)) {
+                throw new Error(`Missing required layer: ${layer}`);
+            }
+            if (typeof data[layer] !== "object" || data[layer] === null) {
+                throw new Error(`Layer ${layer} must be an object`);
+            }
+        }
+        // layer_1 and layer_2 require a "tools" list; layer_3 is implicit
+        for (const layer of ["layer_1_skip", "layer_2_shell"]) {
+            if (!("tools" in data[layer])) {
+                throw new Error(`Layer ${layer} missing 'tools' field`);
+            }
+            if (!Array.isArray(data[layer].tools)) {
+                throw new Error(`Layer ${layer}.tools must be an array`);
+            }
+        }
+        return data;
+    }
+    catch (error) {
+        console.error("[tokenless] Failed to load tool_categories.json:", error);
+        return fallback;
+    }
+}
+// ---- Plugin entry point -------------------------------------------------------
+export default {
+    id: "tokenless",
+    name: "Tokenless",
+    version: "1.0.0",
+    description: "Unified RTK command rewriting + response/TOON compression + hard-disabled Tool Ready",
+    register(api) {
+        const pluginConfig = api.config ?? {};
+        const rtkEnabled = pluginConfig.rtk_enabled !== false;
+        const responseCompressionEnabled = pluginConfig.response_compression_enabled !== false;
+        const toonCompressionEnabled = pluginConfig.toon_compression_enabled === true;
+        const toolReadyEnabled = pluginConfig.tool_ready_enabled !== false;
+        // Load unified tool categories from JSON (single source of truth)
+        const toolCategories = loadToolCategories();
+        // Layer 1: Skip all compression (preserve integrity for content retrieval)
+        // Use config override if provided and non-empty, otherwise use unified categories.
+        // NOTE: `??` alone is insufficient — openclaw may inject the schema default `[]`
+        // which is not nullish, so we also check `.length` to fall through to the JSON.
+        const skipTools = new Set((pluginConfig.skip_tools?.length ? pluginConfig.skip_tools : toolCategories.layer_1_skip.tools)
+            .map((t) => t.toLowerCase()));
+        // Layer 2: Moderate truncation for shell/exec tools
+        // Use config override if provided and non-empty, otherwise use unified categories
+        const shellTools = new Set((pluginConfig.shell_tools?.length ? pluginConfig.shell_tools : toolCategories.layer_2_shell.tools)
+            .map((t) => t.toLowerCase()));
+        // Thresholds are read from tool_categories.json (single source of truth).
+        // Hardcoded fallbacks match the JSON defaults.
+        // 64K strings: 95% of real shell output preserved (git diff ~63K, git log ~34K).
+        // 128 arrays: 95% of result sets preserved (test results, audit reports).
+        const shellThresholds = [
+            toolCategories.layer_2_shell.thresholds?.truncate_strings_at ?? 65536,
+            toolCategories.layer_2_shell.thresholds?.truncate_arrays_at ?? 128,
+            toolCategories.layer_2_shell.thresholds?.max_depth ?? 8,
+        ];
+        const apiThresholds = [
+            toolCategories.layer_3_api.thresholds?.truncate_strings_at ?? 1048576,
+            toolCategories.layer_3_api.thresholds?.truncate_arrays_at ?? 65536,
+            toolCategories.layer_3_api.thresholds?.max_depth ?? 32,
+        ];
+        const verbose = pluginConfig.verbose !== false;
+        // ---- 0. Session mapping (sessionKey → sessionId) ---------------------------
+        api.on("session_start", (event) => {
+            if (event.sessionKey && event.sessionId) {
+                sessionMap.set(event.sessionKey, event.sessionId);
+            }
+            envContext.sessionId = event.sessionId;
+        });
+        // ---- 1. Registered hard-disabled Tool Ready hook (before_tool_call) ---------
+        if (toolReadyEnabled && checkTokenless()) {
+            api.on("before_tool_call", (event, ctx) => {
+                // Full 4-phase flow: Lookup → Check → Fix → Feedback
+                // Returns null for UNKNOWN/READY/post-fix-success (continue silently).
+                // Returns diagnostic only when fix fails (feedback to Agent).
+                const result = tryEnvCheck(event.toolName);
+                if (!result)
+                    return;
+                if (verbose) {
+                    console.log(`[tokenless:ready] ${event.toolName}: ${result.status} — tool not available`);
+                }
+                return { contextPrefix: result.diagnostic };
+            }, { priority: 5 });
+        }
+        // ---- 2. RTK command rewriting (before_tool_call) ----------------------------
+        if (rtkEnabled && checkRtk()) {
+            api.on("before_tool_call", (event, ctx) => {
+                if (event.toolName !== "exec")
+                    return;
+                const command = event.params?.command;
+                if (typeof command !== "string")
+                    return;
+                // Snapshot each call so a missing ID never inherits the previous tool call.
+                const callContext = {
+                    agentId: "openclaw",
+                    sessionId: ctx?.sessionId
+                        || (ctx?.sessionKey && sessionMap.get(ctx.sessionKey))
+                        || "",
+                    toolCallId: ctx?.toolCallId || "",
+                };
+                Object.assign(envContext, callContext);
+                const rewritten = tryRtkRewrite(command, callContext);
+                if (!rewritten)
+                    return;
+                // Keep the established file protocol for older launch paths. Current
+                // OpenClaw exec processes receive the same context directly below, so
+                // concurrent sessions do not depend on this last-write-wins fallback.
+                writeRewriteContext(callContext);
+                if (verbose) {
+                    console.log(`[tokenless:rtk] rewrite: ${command} -> ${rewritten}`);
+                }
+                return {
+                    params: {
+                        ...event.params,
+                        command: rewritten,
+                        env: mergeExecContextEnv(event.params, callContext),
+                    },
+                };
+            }, { priority: 10 });
+        }
+        // ---- 3. Response / TOON compression (tool_result_persist) -------------------
+        // Pipeline: Response Compression → TOON (sequential, not mutually exclusive)
+        //   1. Strip debug/nulls/empty, truncate long strings/arrays
+        //   2. If result is still valid JSON and TOON is enabled, encode to TOON format
+        if (checkTokenless() && (responseCompressionEnabled || toonCompressionEnabled)) {
+            api.on("tool_result_persist", (event, ctx) => {
+                const beforeJson = JSON.stringify(event.message);
+                // Skip small responses
+                if (beforeJson.length < 200)
+                    return;
+                // Skip content-retrieval tools — agent needs complete responses
+                if (event.toolName && skipTools.has(event.toolName.toLowerCase()))
+                    return;
+                // 3-layer dispatch: determine thresholds based on tool category
+                const toolNameLower = (event.toolName ?? "").toLowerCase();
+                const thresholds = shellTools.has(toolNameLower) ? shellThresholds : apiThresholds;
+                // Skip skill content to avoid breaking YAML frontmatter metadata.
+                if (isSkillContent(event.message))
+                    return;
+                const toolCallId = ctx?.toolCallId || event.toolCallId;
+                // Resolve sessionId with 4-level priority:
+                //   1. ctx.sessionId   — direct from OpenClaw (newer versions)
+                //   2. sessionMap[sessionKey] — from session_start mapping
+                //   3. envContext.sessionId — from session_start / before_tool_call
+                //   4. ctx.sessionKey  — always available ("agent:main:main"), best-effort fallback
+                const sessionId = ctx?.sessionId
+                    || (ctx?.sessionKey && sessionMap.get(ctx.sessionKey))
+                    || envContext.sessionId
+                    || ctx?.sessionKey;
+                // Step 1: Response Compression
+                let currentMessage = event.message;
+                let usedResponseCompression = false;
+                if (responseCompressionEnabled) {
+                    const compressed = tryCompressResponse(currentMessage, sessionId, toolCallId, thresholds);
+                    if (compressed) {
+                        currentMessage = compressed;
+                        usedResponseCompression = true;
+                    }
+                }
+                // Step 2: TOON Encoding (if compressed result is JSON-serializable)
+                let usedToon = false;
+                let toonText = "";
+                if (toonCompressionEnabled && checkTokenless()) {
+                    const result = tryCompressToon(currentMessage, sessionId, toolCallId);
+                    if (result) {
+                        toonText = result.toonText;
+                        usedToon = true;
+                    }
+                }
+                // Nothing was compressed — pass through unchanged
+                if (!usedResponseCompression && !usedToon)
+                    return;
+                // Build the final output
+                let finalMessage;
+                let savingsLabel;
+                let totalSavingsPct;
+                if (usedToon) {
+                    const before = beforeJson.length;
+                    const after = toonText.length;
+                    totalSavingsPct = before > 0 ? Math.round(((before - after) / before) * 100) : 0;
+                    savingsLabel = usedResponseCompression
+                        ? "response compressed + TOON encoded"
+                        : "TOON encoded";
+                    // Preserve original tool result message structure. Returning a raw
+                    // string causes OpenClaw's tool_result_persist hook to drop
+                    // role/toolCallId/toolName, which makes session-transcript-repair
+                    // inject a synthetic "missing tool result" error on the next run.
+                    if (typeof event.message === "object" && event.message?.role === "toolResult") {
+                        finalMessage = {
+                            ...event.message,
+                            content: [{ type: "text", text: toonText }],
+                        };
+                    }
+                    else {
+                        finalMessage = toonText;
+                    }
+                }
+                else {
+                    const before = beforeJson.length;
+                    const after = JSON.stringify(currentMessage).length;
+                    totalSavingsPct = before > 0 ? Math.round(((before - after) / before) * 100) : 0;
+                    savingsLabel = "response compressed";
+                    finalMessage = currentMessage;
+                }
+                if (verbose) {
+                    const before = beforeJson.length;
+                    const after = usedToon ? toonText.length : JSON.stringify(finalMessage).length;
+                    console.log(`[tokenless:${savingsLabel}] ${event.toolName}: ${before} -> ${after} chars (${totalSavingsPct}% reduction)`);
+                }
+                return { message: finalMessage };
+            }, { priority: 10 });
+        }
+        // ---- Done -------------------------------------------------------------------
+        if (verbose) {
+            const features = [
+                rtkEnabled && rtkAvailable ? "rtk-rewrite" : null,
+                responseCompressionEnabled && tokenlessAvailable ? "response-compression" : null,
+                toonCompressionEnabled && tokenlessAvailable ? "toon-compression" : null,
+            ].filter(Boolean);
+            console.log(`[tokenless] OpenClaw plugin registered — active features: ${features.join(", ") || "none"}`);
+        }
+    },
+};