anolisa-tokenless 0.7.7

package/adapters/tokenless/openclaw/index.ts

@@ -0,0 +1,720 @@
+/**
+ * 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: Map<string, string> = new Map();
+
+// ---- In-memory env context (replaces global process.env mutation) -------------
+
+interface TokenlessCallContext {
+  agentId: string;
+  sessionId: string;
+  toolCallId: string;
+}
+
+const envContext: TokenlessCallContext = {
+  agentId: "openclaw", sessionId: "", toolCallId: "",
+};
+
+function buildEnv(context: TokenlessCallContext = envContext): Record<string, string> {
+  return {
+    ...process.env as Record<string, string>,
+    ...buildContextEnv(context),
+  };
+}
+
+function buildContextEnv(context: TokenlessCallContext): Record<string, string> {
+  return {
+    TOKENLESS_AGENT_ID: context.agentId,
+    TOKENLESS_SESSION_ID: context.sessionId,
+    TOKENLESS_TOOL_USE_ID: context.toolCallId,
+  };
+}
+
+function mergeExecContextEnv(
+  params: Record<string, unknown>,
+  context: TokenlessCallContext,
+): Record<string, string> {
+  const existingEnv = params.env;
+  const normalizedEnv = typeof existingEnv === "object"
+    && existingEnv !== null
+    && !Array.isArray(existingEnv)
+    ? existingEnv as Record<string, string>
+    : {};
+
+  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: boolean | null = null;
+let rtkCheckedAt: number | null = null;
+let tokenlessAvailable: boolean | null = null;
+let tokenlessCheckedAt: number | null = 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: string = "rtk";
+let tokenlessPath: string = "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: string | null, name: string): string {
+  return directory ? join(directory, name) : "";
+}
+
+// Check both existence and execute permission (mirrors shell `-x` test).
+function isExecutable(path: string): boolean {
+  try {
+    return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBinaryPath(name: string, ...fallbacks: string[]): string | null {
+  // 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(): boolean {
+  // 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: any): boolean {
+  // 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(): boolean {
+  // 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: string, context: TokenlessCallContext): string | null {
+  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: TokenlessCallContext): void {
+  if (!REWRITE_CONTEXT_DIR || !REWRITE_CONTEXT_FILE) {
+    console.warn("[tokenless:rtk] cannot persist rewrite context: HOME is unavailable");
+    return;
+  }
+
+  let fd: number | null = 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 as NodeJS.ErrnoException)?.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: any, sessionId?: string, toolCallId?: string, thresholds?: [number, number, number]): any | null {
+  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: any, sessionId?: string, toolCallId?: string): { toonText: string; savingsPct: number } | null {
+  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: string): { status: string; diagnostic: string } | null {
+  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: string = 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: string = 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: string = fixParsed.diagnostic
+      || `[tokenless:ready] ${toolName}: NOT_READY. Skip retry.`;
+    return { status: postStatus, diagnostic };
+  } catch {
+    return null;
+  }
+}
+
+// ---- Unified tool categorization ---------------------------------------------
+// Load tool categories from tool_categories.json (single source of truth)
+// This ensures consistency with Python hooks and tool-ready-spec.json
+
+interface Thresholds {
+  truncate_strings_at: number;
+  truncate_arrays_at: number;
+  max_depth: number;
+}
+
+interface ToolCategories {
+  layer_1_skip: { tools: string[] };
+  layer_2_shell: { tools: string[]; thresholds?: Thresholds };
+  layer_3_api: { thresholds?: Thresholds };
+}
+
+// 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: string[] = [
+  "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: string[] = [
+  "Bash", "bash", "Shell", "shell", "exec", "terminal",
+  "run_shell_command", "run_in_terminal", "get_terminal_output",
+  "execute_command", "process",
+];
+
+function loadToolCategories(): ToolCategories {
+  const fallback: ToolCategories = {
+    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: string | null = 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 as ToolCategories;
+  } 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: any) {
+  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: Set<string> = new Set(
+    (pluginConfig.skip_tools?.length ? pluginConfig.skip_tools : toolCategories.layer_1_skip.tools)
+      .map((t: string) => t.toLowerCase())
+  );
+
+  // Layer 2: Moderate truncation for shell/exec tools
+  // Use config override if provided and non-empty, otherwise use unified categories
+  const shellTools: Set<string> = new Set(
+    (pluginConfig.shell_tools?.length ? pluginConfig.shell_tools : toolCategories.layer_2_shell.tools)
+      .map((t: string) => 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: [number, number, number] = [
+    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: [number, number, number] = [
+    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: { sessionId: string; sessionKey?: string; resumedFrom?: string }) => {
+      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: { toolName: string; params: Record<string, unknown> }, ctx: { sessionId?: string; sessionKey?: string; agentId?: string; toolCallId?: string; runId?: string }) => {
+        // 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: { toolName: string; params: Record<string, unknown> }, ctx: { sessionId?: string; sessionKey?: string; agentId?: string; toolCallId?: string; runId?: string }) => {
+        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: TokenlessCallContext = {
+          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: { toolName?: string; toolCallId?: string; message: any; isSynthetic?: boolean }, ctx: { agentId?: string; sessionId?: string; sessionKey?: string; toolName?: string; toolCallId?: string }) => {
+        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: any = 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: any;
+        let savingsLabel: string;
+        let totalSavingsPct: number;
+
+        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" as const, 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"}`);
+  }
+  },
+};