feat: trim-tool-result + list-tool-results for agent-driven session pruning

Two new openclaw tools that let an agent reclaim ctx tokens consumed by
past tool results once it has extracted what it needs:

  list-tool-results — enumerates past toolResults in the agent's own
    session jsonl (size, tool name, turns-ago, args summary, already-
    trimmed flag); does NOT return content body
  trim-tool-result — replaces a past toolResult's content[].text with a
    short sentinel-tagged replacement, identified by tool_call_id

The actual file rewrite is deferred to the `agent_end` hook (drained
from an in-memory queue) because writing during tool execute() trips
openclaw's session-file fence (EmbeddedAttemptSessionTakeoverError) —
the fingerprint check around releaseForPrompt rejects third-party
writes. By agent_end the lock window is closed and the next turn's
fence baseline picks up our mutation cleanly.

Queue-time validation rejects bad tool_call_ids up-front so weak
models that confuse opaque call_function_*_N ids with topic/fact
numeric ids get a clear error instead of a silent skip at drain time.

install.mjs now auto-sets plugins.entries.padded-cell.hooks.
allowConversationAccess=true (required for the agent_end hook on
non-bundled plugins; without it the drain never fires and queued
trims rot in memory).

Sim-verified end-to-end: model dispatches trim, drain fires on
agent_end, next turn's list shows already_trimmed=true.

plugin/index.ts

@@ -3,10 +3,16 @@
 
 import os from 'node:os';
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
 
 import { pcexec, pcexecSync } from './tools/pcexec.js';
+import {
+  queueTrimToolResult,
+  listToolResults,
+  drainTrimQueueForSession,
+} from './tools/session-rewrite.js';
 import {
   safeRestart,
   createSafeRestartTool,
@@ -186,6 +192,82 @@ function register(api: OpenClawPluginApi): void {
     } as any;
   });
 
+  // Register trim-tool-result — rewrite a past toolResult to free ctx tokens.
+  api.registerTool((ctx) => {
+    const agentDir = ctx.agentDir;
+    const agentIdInner = ctx.agentId;
+    const sessionId = ctx.sessionId;
+    return {
+      name: 'trim-tool-result',
+      description:
+        'Replace a past tool result in your own session with a shorter version (or empty sentinel). Use after extracting what you need from a noisy tool output to free ctx tokens. Irreversible — re-run the original tool if you mis-trim.',
+      parameters: {
+        type: 'object',
+        properties: {
+          tool_call_id: {
+            type: 'string',
+            description: 'The id of the toolCall whose result you want to trim (from list-tool-results).',
+          },
+          replacement: {
+            type: 'string',
+            description: 'Optional condensed text to keep. Omit to fully elide the result.',
+          },
+        },
+        required: ['tool_call_id'],
+      },
+      async execute(_id: string, params: any) {
+        const r = queueTrimToolResult(
+          { agentDir, agentId: agentIdInner, sessionId },
+          {
+            tool_call_id: String(params.tool_call_id ?? ''),
+            replacement: params.replacement != null ? String(params.replacement) : undefined,
+          },
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(r) }] };
+      },
+    } as any;
+  });
+
+  // Register list-tool-results — enumerate past toolResults to pick trim candidates.
+  api.registerTool((ctx) => {
+    const agentDir = ctx.agentDir;
+    const agentIdInner = ctx.agentId;
+    const sessionId = ctx.sessionId;
+    return {
+      name: 'list-tool-results',
+      description:
+        'List past toolResults in your own session ordered by size (largest first), with tool name, args summary, byte size, and turns-ago. Does NOT include the result content itself — use this to pick trim-tool-result targets without re-reading bulky outputs.',
+      parameters: {
+        type: 'object',
+        properties: {
+          min_bytes: { type: 'number', description: 'Only include results at least this many bytes.' },
+          older_than_turns: {
+            type: 'number',
+            description: 'Only include results from at least this many assistant turns ago (default 0).',
+          },
+          include_trimmed: {
+            type: 'boolean',
+            description: 'Include already-trimmed results (default false).',
+          },
+          limit: { type: 'number', description: 'Max entries to return (default 50).' },
+        },
+      },
+      async execute(_id: string, params: any) {
+        const r = await listToolResults(
+          { agentDir, agentId: agentIdInner, sessionId },
+          {
+            min_bytes: typeof params.min_bytes === 'number' ? params.min_bytes : undefined,
+            older_than_turns:
+              typeof params.older_than_turns === 'number' ? params.older_than_turns : undefined,
+            include_trimmed: params.include_trimmed === true,
+            limit: typeof params.limit === 'number' ? params.limit : undefined,
+          },
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(r) }] };
+      },
+    } as any;
+  });
+
   // Register /ego-mgr slash command if the host exposes the (non-standard) hook.
   // This API is not part of the current OpenClawPluginApi surface; the guard
   // makes the plugin a no-op for slash commands when the host doesn't support
@@ -212,6 +294,48 @@ function register(api: OpenClawPluginApi): void {
     logger.info('Registered /ego-mgr slash command');
   }
 
+  // agent_end hook drains the trim queue AFTER openclaw's session-file fence
+  // window closes. Writing during execute() would trip
+  // EmbeddedAttemptSessionTakeoverError because the lock-released fingerprint
+  // check sees our mutation as a third-party takeover. By agent_end the lock
+  // is in its between-turns state and the next turn's fence snapshot will
+  // include our trim as baseline.
+  const apiOn = (api as unknown as { on?: (ev: string, fn: (...args: unknown[]) => unknown) => void }).on;
+  if (typeof apiOn === 'function') {
+    apiOn.call(api, 'agent_end', async (_event: unknown, ctx: unknown) => {
+      const c = (ctx ?? {}) as { agentId?: string; agentDir?: string; sessionId?: string };
+      if (!c.sessionId) return;
+      try {
+        // Resolve the same file the tool resolved (canonical path priority).
+        let sessionFile: string | null = null;
+        const tryPaths: string[] = [];
+        if (c.agentId) {
+          tryPaths.push(path.join(openclawPath, 'agents', c.agentId, 'sessions', `${c.sessionId}.jsonl`));
+        }
+        if (c.agentDir) {
+          tryPaths.push(path.join(c.agentDir, 'sessions', `${c.sessionId}.jsonl`));
+          const stripped = c.agentDir.replace(/\/agent$/, '');
+          if (stripped !== c.agentDir) {
+            tryPaths.push(path.join(stripped, 'sessions', `${c.sessionId}.jsonl`));
+          }
+        }
+        for (const p of tryPaths) {
+          if (existsSync(p)) { sessionFile = p; break; }
+        }
+        if (!sessionFile) return;
+        const r = await drainTrimQueueForSession(sessionFile);
+        if (r && (r.applied > 0 || r.skipped > 0 || r.errors.length > 0)) {
+          logger.info(
+            `trim-tool-result drain: session=${c.sessionId} applied=${r.applied} skipped=${r.skipped} trimmed_bytes=${r.trimmed_bytes}` +
+              (r.errors.length ? ` errors=${r.errors.length}` : ''),
+          );
+        }
+      } catch (err) {
+        logger.warn(`trim-tool-result agent_end drain failed: ${err}`);
+      }
+    });
+  }
+
   logger.info('PaddedCell plugin initialized');
 }