feat(dynamic-trim): rename trim-tool-result, add self-compact, drop list-tool-results

Align the openclaw side of the dynamic-* tool family with the new
Plexum design (decision #31, 2026-06-04 revision):

- trim-tool-result → dynamic-trim (same on-wire schema; same semantics)
- Drop list-tool-results entirely. Agents find the opaque tool_call_id
  by reading their own prior assistant message's toolCall block id
  instead of querying a separate "directory" tool. This removes a
  workflow-step prerequisite and matches how Anthropic-shaped APIs
  surface tool_use ids to the model anyway.
- On agent_end drain, ALSO self-compact the dynamic-trim's own
  tool_use.input: rewrite to {tool_call_id, _self_compacted: true}.
  Without this the bulky `replacement` text sits duplicated — once in
  the rewritten target tool_result, once in dynamic-trim's call input.
  Picks up the selfCallId from openclaw's execute(toolCallId, ...) first
  arg (was previously discarded as _id).

Cross-runtime contract: tool name, input schema, return shape, and
sentinel prefix ("[trimmed by self] ") match Plexum's dynamic-trim
in internal/dynmem/trim.go + internal/persistence/trim.go.

Sim e2e tested: dynamic-trim queues, agent_end drain rewrites both
the target tool_result content AND the trim call's tool_use input.
No takeover errors. trimmed_bytes positive on real workloads.

plugin/index.ts

@@ -9,8 +9,7 @@ import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
 
 import { pcexec, pcexecSync } from './tools/pcexec.js';
 import {
-  queueTrimToolResult,
+  queueDynamicTrim,
-  listToolResults,
   drainTrimQueueForSession,
 } from './tools/session-rewrite.js';
 import {
@@ -192,76 +191,50 @@ function register(api: OpenClawPluginApi): void {
     } as any;
   });
 
-  // Register trim-tool-result — rewrite a past toolResult to free ctx tokens.
+  // Register dynamic-trim — agent-driven rewrite of a past tool_result
+  // block. On the next turn boundary (agent_end hook) the target tool
+  // result's content[].text is shrunk AND this dynamic-trim call's own
+  // tool_use input is also self-compacted to {tool_call_id, _self_compacted}
+  // so the bulky replacement text doesn't sit duplicated.
+  //
+  // Cross-runtime alignment with Plexum's dynamic-* family — same tool
+  // name, same input schema, same semantics; only the lifecycle hook name
+  // differs (openclaw agent_end / Plexum block mutation point).
   api.registerTool((ctx) => {
     const agentDir = ctx.agentDir;
     const agentIdInner = ctx.agentId;
     const sessionId = ctx.sessionId;
     return {
-      name: 'trim-tool-result',
+      name: 'dynamic-trim',
       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.',
+        'Rewrite a past tool_result block in your own session to a shorter version (or sentinel). ' +
+        'Use after extracting what you need from a noisy tool output to free ctx tokens for future turns. ' +
+        'The tool_call_id is the OPAQUE id (looks like "call_function_abc123_1") of the prior tool_use — ' +
+        'find it in your own prior assistant messages; topic/fact ids and small integers will NOT work here. ' +
+        'Irreversible — re-run the original tool if you mis-trim. ' +
+        'Side effect: this dynamic-trim call\'s own tool_use input is self-compacted on the same turn boundary.',
       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).',
+            description: 'The opaque id of the target tool_use (you find this by reading your own prior assistant messages — the id appears on each toolCall block).',
           },
           replacement: {
             type: 'string',
-            description: 'Optional condensed text to keep. Omit to fully elide the result.',
+            description: 'Optional condensed text to keep in place of the original result. Omit / empty = full elide.',
           },
         },
         required: ['tool_call_id'],
       },
-      async execute(_id: string, params: any) {
+      async execute(selfCallId: string, params: any) {
-        const r = queueTrimToolResult(
+        const r = queueDynamicTrim(
           { agentDir, agentId: agentIdInner, sessionId },
           {
             tool_call_id: String(params.tool_call_id ?? ''),
             replacement: params.replacement != null ? String(params.replacement) : undefined,
           },
-        );
+          selfCallId,
-        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) }] };
       },

plugin/openclaw.plugin.json

@@ -10,8 +10,7 @@
       "pcexec",
       "proxy-pcexec",
       "safe_restart",
-      "trim-tool-result",
+      "dynamic-trim"
-      "list-tool-results"
     ]
   },
   "configSchema": {

plugin/tools/session-rewrite.ts

@@ -1,13 +1,19 @@
-// Tools that operate on the calling agent's own session JSONL file.
+// `dynamic-trim` — agent-driven tool_result rewrite tool.
 //
-// `trimToolResult` rewrites a past toolResult's content[].text by toolCallId,
+// The agent picks a past toolResult block by toolCallId and supplies a
-// shrinking context that the agent has already extracted what it needs from.
+// short `replacement` string; on the next turn boundary (agent_end hook)
-// `listToolResults` enumerates past toolResults (size + tool + turns-ago) so
+// the session jsonl is rewritten so that:
-// the agent can pick trim candidates without re-reading their content.
 //
-// Both operate directly on the canonical session file at
+//   1. The target toolResult.content[].text becomes
-//   <agentDir>/sessions/<sessionId>.jsonl
+//      "[trimmed by self] <replacement>"
-// No backup is kept — if a trim turns out wrong, re-run the original tool.
+//   2. The dynamic-trim call's OWN tool_use input is rewritten to
+//      {"tool_call_id":"<id>","_self_compacted":true}
+//      so the bulky replacement text doesn't sit duplicated in two places.
+//
+// Operates directly on <openclaw>/agents/<agentId>/sessions/<sid>.jsonl.
+// No faithful audit — irreversible by design (re-run the original tool
+// if you trim wrong). See WORKFLOW-TOOLS-COMPLETION-REQUEST.md in Plexum
+// docs/ for the cross-runtime contract.
 
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -33,16 +39,13 @@ function resolveSessionFile(ctx: SessionRewriteCtx): string {
     throw new Error('session context missing sessionId (no active session?)');
   }
   const candidates: string[] = [];
-  // canonical: <OPENCLAW>/agents/<agentId>/sessions/<sid>.jsonl
   if (ctx.agentId) {
     candidates.push(
       path.join(openclawRoot(), 'agents', ctx.agentId, 'sessions', `${ctx.sessionId}.jsonl`),
     );
   }
-  // fallback A: <agentDir>/sessions/<sid>.jsonl
   if (ctx.agentDir) {
     candidates.push(path.join(ctx.agentDir, 'sessions', `${ctx.sessionId}.jsonl`));
-    // fallback B: strip trailing "/agent" if openclaw config put it there
     const stripped = ctx.agentDir.replace(/\/agent$/, '');
     if (stripped !== ctx.agentDir) {
       candidates.push(path.join(stripped, 'sessions', `${ctx.sessionId}.jsonl`));
@@ -62,73 +65,95 @@ interface MessageEvent {
     role?: string;
     toolCallId?: string;
     toolName?: string;
-    content?: Array<{ type?: string; text?: string }>;
+    content?: Array<{
+      type?: string;
+      text?: string;
+      id?: string;         // toolCall block id
+      name?: string;       // toolCall block name
+      arguments?: unknown; // toolCall block arguments — what we self-compact
+    }>;
   };
 }
 
-export interface TrimToolResultParams {
+export interface DynamicTrimParams {
   tool_call_id: string;
   replacement?: string;
 }
 
-export interface TrimToolResultResult {
+export interface DynamicTrimResult {
   ok: true;
   status: 'queued';
   tool_call_id: string;
+  self_compacted: true;
   applies_at: 'agent_end';
   note: string;
 }
 
 interface QueuedTrim {
-  tool_call_id: string;
+  targetCallId: string;   // the past tool_result we want to rewrite
-  replacement?: string;
+  replacement?: string;   // agent-supplied summary
+  selfCallId: string;     // the dynamic-trim's OWN tool_use id; gets self-compacted
 }
-// Module-scope queue keyed by absolute session file path. Drained from the
+
-// `agent_end` hook (see index.ts) — writing during tool execute trips
+// Module-scope queue keyed by absolute session file path. Drained from
-// openclaw's session-file fence (EmbeddedAttemptSessionTakeoverError) because
+// the `agent_end` hook (see index.ts). Writing during tool execute trips
-// the fingerprint check around releaseForPrompt rejects third-party writes.
+// openclaw's session-file fence (EmbeddedAttemptSessionTakeoverError)
+// because the fingerprint check around releaseForPrompt rejects third-
+// party writes; agent_end fires AFTER that fence window closes.
 const trimQueue = new Map<string, QueuedTrim[]>();
 
-export function queueTrimToolResult(
+/**
+ * Enqueue a dynamic-trim mutation. Returns synchronously to the agent
+ * with a "queued" status; the actual file rewrite happens on agent_end.
+ */
+export function queueDynamicTrim(
   ctx: SessionRewriteCtx,
-  params: TrimToolResultParams,
+  params: DynamicTrimParams,
-): TrimToolResultResult {
+  selfCallId: string,
+): DynamicTrimResult {
   if (!params.tool_call_id) {
     throw new Error('missing required parameter: tool_call_id');
   }
+  if (!selfCallId) {
+    throw new Error(
+      'dynamic-trim: cannot identify self tool_use id (openclaw runtime should pass it to execute as first arg)',
+    );
+  }
   const sessionFile = resolveSessionFile(ctx);
-  // Validate the toolCallId actually points at a real toolResult in this
+  // Validate the target id BEFORE queueing — otherwise agent learns of the
-  // session. Without this check the drain would silently skip a bad id and
+  // mistake only in the drain log. Weak models occasionally pass topic ids
-  // the agent would not learn of the mistake until reading the gateway log
+  // / fact ids / small integers thinking they're tool_use ids.
-  // — a frequent failure mode for weak models that confuse opaque
-  // `call_function_*_N` ids with topic/fact numeric ids.
   if (!sessionHasToolResult(sessionFile, params.tool_call_id)) {
     throw new Error(
       `tool_call_id "${params.tool_call_id}" does not match any toolResult in this session. ` +
-        `Call list-tool-results first to copy a real id (long opaque string like "call_function_abc123_1"). ` +
+        `Find the opaque "call_function_*_N" id in your own prior assistant messages — ` +
-        `Topic ids, fact ids, and small integers will not work here.`,
+        `topic ids, fact ids, and small integers will not work here.`,
     );
   }
   const list = trimQueue.get(sessionFile) ?? [];
-  list.push({ tool_call_id: params.tool_call_id, replacement: params.replacement });
+  list.push({
+    targetCallId: params.tool_call_id,
+    replacement: params.replacement,
+    selfCallId,
+  });
   trimQueue.set(sessionFile, list);
   return {
     ok: true,
     status: 'queued',
     tool_call_id: params.tool_call_id,
+    self_compacted: true,
     applies_at: 'agent_end',
-    note: 'Trim will be applied to the session file after this turn ends. The smaller ctx takes effect on the next turn.',
+    note:
+      'Trim queued. On this turn end the target tool_result text is shrunk AND this dynamic-trim ' +
+      'call\'s own tool_use input is replaced with {tool_call_id, _self_compacted:true}. ' +
+      'Effect visible in next turn\'s context.',
   };
 }
 
 function sessionHasToolResult(sessionFile: string, toolCallId: string): boolean {
-  // Cheap streaming check — scan lines for the toolCallId substring before
-  // committing to JSON.parse for confirmation.
   const raw = fs.readFileSync(sessionFile, 'utf8');
   const needle = `"toolCallId":"${toolCallId}"`;
   if (!raw.includes(needle)) return false;
-  // Defend against the id appearing inside arbitrary text (e.g. a prior
-  // assistant message quoting the id) by confirming a structural match.
   for (const line of raw.split('\n')) {
     if (!line.includes(needle)) continue;
     try {
@@ -141,7 +166,7 @@ function sessionHasToolResult(sessionFile: string, toolCallId: string): boolean
         return true;
       }
     } catch {
-      // skip malformed line
+      /* skip malformed */
     }
   }
   return false;
@@ -152,6 +177,7 @@ export interface DrainResult {
   applied: number;
   skipped: number;
   trimmed_bytes: number;
+  self_compacted: number; // how many of the dynamic-trim tool_use inputs we shrank
   errors: string[];
 }
 
@@ -168,18 +194,28 @@ export async function drainTrimQueueForSession(
       applied: 0,
       skipped: queued.length,
       trimmed_bytes: 0,
+      self_compacted: 0,
       errors: [`session file vanished: ${sessionFile}`],
     };
   }
 
   const raw = await fs.promises.readFile(sessionFile, 'utf8');
   const lines = raw.split('\n');
-  const targets = new Map<string, QueuedTrim>();
+
-  for (const q of queued) targets.set(q.tool_call_id, q);
+  // Build lookup maps.
+  // targetsByCallId: tool_result id → queued mutation
+  // selfByCallId:    dynamic-trim tool_use id → queued mutation (for self-compact)
+  const targetsByCallId = new Map<string, QueuedTrim>();
+  const selfByCallId = new Map<string, QueuedTrim>();
+  for (const q of queued) {
+    targetsByCallId.set(q.targetCallId, q);
+    selfByCallId.set(q.selfCallId, q);
+  }
 
   let applied = 0;
   let skipped = 0;
   let trimmedBytes = 0;
+  let selfCompacted = 0;
   const errors: string[] = [];
 
   for (let i = 0; i < lines.length; i++) {
@@ -192,184 +228,90 @@ export async function drainTrimQueueForSession(
       continue;
     }
     if (obj?.type !== 'message') continue;
-    if (obj.message?.role !== 'toolResult') continue;
+    const role = obj.message?.role;
-    const callId = obj.message.toolCallId;
+
-    if (!callId) continue;
+    // (A) toolResult rewrite — target
-    const q = targets.get(callId);
+    if (role === 'toolResult') {
-    if (!q) continue;
+      const callId = obj.message?.toolCallId;
-    const content = obj.message.content;
+      if (!callId) continue;
-    if (!Array.isArray(content) || content.length === 0) {
+      const q = targetsByCallId.get(callId);
-      errors.push(`toolResult ${callId} has no content[] to trim`);
+      if (!q) continue;
-      skipped++;
+      const content = obj.message?.content;
-      targets.delete(callId);
+      if (!Array.isArray(content) || content.length === 0) {
+        errors.push(`toolResult ${callId} has no content[] to trim`);
+        skipped++;
+        targetsByCallId.delete(callId);
+        continue;
+      }
+      const newText = q.replacement
+        ? `${TRIM_SENTINEL} ${q.replacement}`
+        : TRIM_SENTINEL;
+      let touched = false;
+      for (const c of content) {
+        if (c?.type === 'text' && typeof c.text === 'string') {
+          trimmedBytes += Buffer.byteLength(c.text, 'utf8') - Buffer.byteLength(newText, 'utf8');
+          c.text = newText;
+          touched = true;
+        }
+      }
+      if (!touched) {
+        errors.push(`toolResult ${callId} has no text blocks`);
+        skipped++;
+        targetsByCallId.delete(callId);
+        continue;
+      }
+      lines[i] = JSON.stringify(obj);
+      applied++;
+      targetsByCallId.delete(callId);
       continue;
     }
-    const newText = q.replacement ? `${TRIM_SENTINEL} ${q.replacement}` : TRIM_SENTINEL;
+
-    let touched = false;
+    // (B) assistant message containing the dynamic-trim's own toolCall — self-compact
-    for (const c of content) {
+    if (role === 'assistant') {
-      if (c?.type === 'text' && typeof c.text === 'string') {
+      const content = obj.message?.content;
-        trimmedBytes += Buffer.byteLength(c.text, 'utf8') - Buffer.byteLength(newText, 'utf8');
+      if (!Array.isArray(content)) continue;
-        c.text = newText;
+      let lineChanged = false;
-        touched = true;
+      for (const c of content) {
+        if (c?.type !== 'toolCall') continue;
+        if (typeof c.id !== 'string') continue;
+        const q = selfByCallId.get(c.id);
+        if (!q) continue;
+        // Replace the bulky arguments with the minimal self-compacted form.
+        // Preserves toolCallId for traceability; _self_compacted flag for
+        // tooling (future plexum dynamic-recall etc.) to recognise.
+        c.arguments = { tool_call_id: q.targetCallId, _self_compacted: true };
+        selfByCallId.delete(c.id);
+        lineChanged = true;
+        selfCompacted++;
+      }
+      if (lineChanged) {
+        lines[i] = JSON.stringify(obj);
       }
     }
-    if (!touched) {
-      errors.push(`toolResult ${callId} has no text blocks`);
-      skipped++;
-      targets.delete(callId);
-      continue;
-    }
-    lines[i] = JSON.stringify(obj);
-    applied++;
-    targets.delete(callId);
   }
-  for (const callId of targets.keys()) {
+
+  for (const callId of targetsByCallId.keys()) {
     errors.push(`toolResult ${callId} not found in session`);
     skipped++;
   }
+  for (const selfId of selfByCallId.keys()) {
+    errors.push(`self tool_use ${selfId} not found in session (cannot self-compact)`);
+  }
 
   const tmp = `${sessionFile}.trim.${process.pid}.${Date.now()}`;
   await fs.promises.writeFile(tmp, lines.join('\n'), 'utf8');
   await fs.promises.rename(tmp, sessionFile);
 
-  return { session_file: sessionFile, applied, skipped, trimmed_bytes: trimmedBytes, errors };
+  return {
+    session_file: sessionFile,
+    applied,
+    skipped,
+    trimmed_bytes: trimmedBytes,
+    self_compacted: selfCompacted,
+    errors,
+  };
 }
 
 export function pendingTrimSessions(): string[] {
   return Array.from(trimQueue.keys());
 }
-
-// Back-compat: synchronous adapter retained for direct callers / tests; not
-// used by the registered tool (which routes through the queue).
-export async function trimToolResult(
-  ctx: SessionRewriteCtx,
-  params: TrimToolResultParams,
-): Promise<TrimToolResultResult> {
-  return queueTrimToolResult(ctx, params);
-}
-
-export interface ListToolResultsParams {
-  min_bytes?: number;
-  older_than_turns?: number;
-  include_trimmed?: boolean;
-  limit?: number;
-}
-
-export interface ListToolResultsEntry {
-  tool_call_id: string;
-  tool_name: string;
-  bytes: number;
-  turns_ago: number;
-  arguments_summary: string;
-  already_trimmed: boolean;
-}
-
-export interface ListToolResultsResult {
-  count: number;
-  results: ListToolResultsEntry[];
-}
-
-export async function listToolResults(
-  ctx: SessionRewriteCtx,
-  params: ListToolResultsParams,
-): Promise<ListToolResultsResult> {
-  const minBytes = params.min_bytes ?? 0;
-  const olderThanTurns = params.older_than_turns ?? 0;
-  const includeTrimmed = params.include_trimmed === true;
-  const limit = params.limit ?? 50;
-
-  const sessionFile = resolveSessionFile(ctx);
-  const raw = await fs.promises.readFile(sessionFile, 'utf8');
-  const lines = raw.split('\n');
-
-  interface AssistantToolCall {
-    id: string;
-    args: unknown;
-  }
-  const argsByCallId = new Map<string, unknown>();
-  interface Candidate {
-    toolCallId: string;
-    toolName: string;
-    bytes: number;
-    assistantCountAtTime: number;
-    alreadyTrimmed: boolean;
-  }
-  const candidates: Candidate[] = [];
-  let assistantCount = 0;
-
-  for (const line of lines) {
-    if (!line) continue;
-    let obj: MessageEvent;
-    try {
-      obj = JSON.parse(line) as MessageEvent;
-    } catch {
-      continue;
-    }
-    if (obj?.type !== 'message') continue;
-    const role = obj.message?.role;
-    if (role === 'assistant') {
-      assistantCount++;
-      const content = obj.message?.content;
-      if (Array.isArray(content)) {
-        for (const c of content as Array<{ type?: string; id?: string; arguments?: unknown }>) {
-          if (c?.type === 'toolCall' && typeof c.id === 'string') {
-            argsByCallId.set(c.id, c.arguments);
-          }
-        }
-      }
-    } else if (role === 'toolResult') {
-      const callId = obj.message?.toolCallId;
-      if (!callId) continue;
-      const toolName = obj.message?.toolName ?? '';
-      const content = obj.message?.content;
-      let bytes = 0;
-      let alreadyTrimmed = false;
-      if (Array.isArray(content)) {
-        for (const c of content) {
-          if (c?.type === 'text' && typeof c.text === 'string') {
-            bytes += Buffer.byteLength(c.text, 'utf8');
-            if (c.text.startsWith(TRIM_SENTINEL)) alreadyTrimmed = true;
-          }
-        }
-      }
-      candidates.push({
-        toolCallId: callId,
-        toolName,
-        bytes,
-        assistantCountAtTime: assistantCount,
-        alreadyTrimmed,
-      });
-    }
-  }
-
-  const totalAssistant = assistantCount;
-  const results: ListToolResultsEntry[] = [];
-  for (const c of candidates) {
-    if (!includeTrimmed && c.alreadyTrimmed) continue;
-    if (c.bytes < minBytes) continue;
-    const turnsAgo = totalAssistant - c.assistantCountAtTime;
-    if (turnsAgo < olderThanTurns) continue;
-    const argsRaw = argsByCallId.get(c.toolCallId);
-    let argsSummary = '';
-    if (argsRaw !== undefined) {
-      try {
-        argsSummary = JSON.stringify(argsRaw);
-      } catch {
-        argsSummary = String(argsRaw);
-      }
-      if (argsSummary.length > 200) argsSummary = argsSummary.slice(0, 200) + '…';
-    }
-    results.push({
-      tool_call_id: c.toolCallId,
-      tool_name: c.toolName,
-      bytes: c.bytes,
-      turns_ago: turnsAgo,
-      arguments_summary: argsSummary,
-      already_trimmed: c.alreadyTrimmed,
-    });
-  }
-
-  results.sort((a, b) => b.bytes - a.bytes);
-  const trimmed = results.slice(0, limit);
-  return { count: trimmed.length, results: trimmed };
-}