diff --git a/plugin/index.ts b/plugin/index.ts index f9542b6..e13d0f9 100644 --- a/plugin/index.ts +++ b/plugin/index.ts @@ -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) }] }; }, diff --git a/plugin/openclaw.plugin.json b/plugin/openclaw.plugin.json index ef9ec5d..bfd460e 100644 --- a/plugin/openclaw.plugin.json +++ b/plugin/openclaw.plugin.json @@ -10,8 +10,7 @@ "pcexec", "proxy-pcexec", "safe_restart", - "trim-tool-result", - "list-tool-results" + "dynamic-trim" ] }, "configSchema": { diff --git a/plugin/tools/session-rewrite.ts b/plugin/tools/session-rewrite.ts index 882eb8b..90cdf43 100644 --- a/plugin/tools/session-rewrite.ts +++ b/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, -// 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 -// /sessions/.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] " +// 2. The dynamic-trim call's OWN tool_use input is rewritten to +// {"tool_call_id":"","_self_compacted":true} +// so the bulky replacement text doesn't sit duplicated in two places. +// +// Operates directly on /agents//sessions/.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: /agents//sessions/.jsonl if (ctx.agentId) { candidates.push( path.join(openclawRoot(), 'agents', ctx.agentId, 'sessions', `${ctx.sessionId}.jsonl`), ); } - // fallback A: /sessions/.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(); -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(); - 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(); + const selfByCallId = new Map(); + 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 { - 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 { - 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(); - 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 }; -}