nav/PaddedCell
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
h z
2026-06-04 07:47:30 +01:00
parent 209ab0d82e
commit 0b7f18253d
3 changed files with 167 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
plugin/index.ts
View File

@@ -9,8 +9,7 @@ import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
import { pcexec, pcexecSync } from './tools/pcexec.js';
import {
queueTrimToolResult,
listToolResults,
queueDynamicTrim,
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) {
const r = queueTrimToolResult(
async execute(selfCallId: string, params: any) {
const r = queueDynamicTrim(
{ 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,
},
selfCallId,
);
return { content: [{ type: 'text', text: JSON.stringify(r) }] };
},

3
plugin/openclaw.plugin.json
View File

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

346
plugin/tools/session-rewrite.ts
View File

@@ -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,
// shrinking context that the agent has already extracted what it needs from.
// `listToolResults` enumerates past toolResults (size + tool + turns-ago) so
// the agent can pick trim candidates without re-reading their content.
// The agent picks a past toolResult block by toolCallId and supplies a
// short `replacement` string; on the next turn boundary (agent_end hook)
// the session jsonl is rewritten so that:
//
// Both operate directly on the canonical session file at
// <agentDir>/sessions/<sessionId>.jsonl
// No backup is kept — if a trim turns out wrong, re-run the original tool.
// 1. The target toolResult.content[].text becomes
// "[trimmed by self] <replacement>"
// 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;
replacement?: string;
targetCallId: string; // the past tool_result we want to rewrite
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
// openclaw's session-file fence (EmbeddedAttemptSessionTakeoverError) because
// the fingerprint check around releaseForPrompt rejects third-party writes.
// Module-scope queue keyed by absolute session file path. Drained from
// the `agent_end` hook (see index.ts). Writing during tool execute trips
// 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,
): TrimToolResultResult {
params: DynamicTrimParams,
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
// session. Without this check the drain would silently skip a bad id and
// the agent would not learn of the mistake until reading the gateway log
// — a frequent failure mode for weak models that confuse opaque
// `call_function_*_N` ids with topic/fact numeric ids.
// Validate the target id BEFORE queueing — otherwise agent learns of the
// mistake only in the drain log. Weak models occasionally pass topic ids
// / fact ids / small integers thinking they're tool_use 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"). ` +
`Topic ids, fact ids, and small integers will not work here.`,
`Find the opaque "call_function_*_N" id in your own prior assistant messages — ` +
`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 callId = obj.message.toolCallId;
if (!callId) continue;
const q = targets.get(callId);
if (!q) continue;
const content = obj.message.content;
if (!Array.isArray(content) || content.length === 0) {
errors.push(`toolResult ${callId} has no content[] to trim`);
skipped++;
targets.delete(callId);
const role = obj.message?.role;
// (A) toolResult rewrite — target
if (role === 'toolResult') {
const callId = obj.message?.toolCallId;
if (!callId) continue;
const q = targetsByCallId.get(callId);
if (!q) continue;
const content = obj.message?.content;
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;
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;
// (B) assistant message containing the dynamic-trim's own toolCall — self-compact
if (role === 'assistant') {
const content = obj.message?.content;
if (!Array.isArray(content)) continue;
let lineChanged = false;
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 };
}