fix(openclaw): preserve tool-call thought signatures (#4038)

## Description

Preserve provider metadata while canonicalizing assistant tool calls.
The existing normalization rebuilt a `toolCall` from four fields and
dropped `thoughtSignature`, including on unchanged assistant turns
restored after compressing a different tool result.

Closes #4036. The original dynamic-notice behavior in #3809 is already
addressed on main and is not claimed as a new fix here.

## Type of Change

- [x] Bug fix (non-breaking)
- [x] Documentation update

## Changes Made

- Retain the original tool-call block properties before applying the
existing canonical type/id/name/arguments normalization.
- Keep existing missing-metadata defaults and legacy `tool_use`
normalization; no new options, routes, or dependencies.
- Add a failing-before regression for a signed canonical tool call and
document metadata retention in the existing plugin README.

## Testing

- Plugin: `npm test` — **8 files, 121 tests passed**.
- Plugin: `npm run typecheck` and `npm run build` — passed.
- Regression before the production change: **1 failed, 4 passed**, with
`thoughtSignature` observed as `undefined`.
- Required pre-push `make ci-precheck` — **passed**: complete Rust
workspace formatting, strict Clippy, workspace tests; native extension
build/import verification; Python qualification suite **177 passed, 4
skipped**; Conventional Commit lint.
- Complete Ruff formatting check — **1768 files already formatted**.
- Whole-tree Ruff lint reported five unchanged executable OAuth2 Python
files lacking shebangs; no unrelated chmod or suppression was applied.
- Whole-tree `mypy headroom` checked 566 files and reported one
unchanged `truthy-function` error in
`headroom/integrations/langchain/chat_model.py:394`; no Python
implementation was changed by this PR.
- Complete Python suite — **15,630 passed, 612 skipped, 7 failed**. The
failures are outside the changed plugin: two CLI-import shape errors,
one WebSocket lifecycle timeout, and four Kompress readiness
expectations. These broad failures are not suppressed or claimed green.
- Published GitHub checks — **19 passed, 19 skipped**, with no failed or
pending check at the recorded readiness check.

## Real Behavior Proof

Environment: Linux x86_64, Bun 1.3.13, Node 22.23.1, Python 3.13.14,
repository-pinned Rust 1.95.0; base
`3c418f6f0b190ad1060413c0eadd77f20ab3cf46`.

Actual converter/restorer command: `bun -e` importing
`agentToOpenAIIndexed` and `restoreAgentMessages` from
`plugins/openclaw/src/convert.ts`. The input contains a user turn, a
Google-provider assistant turn with a signed canonical tool call, and a
separate tool result. Only the tool-result text is compressed in the
returned wire messages.

Before: the identical Google-provider fixture run against untouched main
fails its unchanged-assistant deep equality assertion because the tool
call loses `thoughtSignature`.

After:

```text
unchanged_user_byte_exact: true
unchanged_assistant_byte_exact: true
thinking_signature_preserved: true
compressed_tool_text: short tool result
tool_metadata_preserved: true
```

The unchanged-assistant equality includes the tool-call signature and
arguments. This is an actual converter round trip, not a mocked provider
or a forwarding-only test.

Not tested: full OpenClaw gateway installation, paid provider calls,
provider cache-hit rates/billing, macOS, Windows.

## Runtime Rollout Safety

No rollout-managed feature/channel or unsafe override is added. Default
plugin normalization now retains opaque provider tool-call metadata;
canonical defaults remain intact. Disable the OpenClaw plugin to avoid
its context assembly, or revert this three-file commit as rollback.
Existing Rust/Python qualification remains passing as recorded above.

## Review Readiness

- [x] Existing conversion consumers, normalization defaults, and scope
reviewed
- [x] This PR is ready for human review; all broad-check outcomes are
recorded, including unrelated Python limitations

## Checklist

- [x] Corresponding documentation updated
- [x] Regression proves the fix is effective
- [x] No new warnings observed in the changed plugin
- [x] No `CHANGELOG.md` edit (release-please owns it)

## Additional Notes

Fresh duplicate check covered all 195 open PRs. #4034 preserves
signatures in Python CCR handling and does not modify this OpenClaw
normalizer. AI-assisted: omp / GPT-6.1 Sol.
This commit is contained in:
Mansurshakh Japarov
2026-10-08 10:19:33 -05:00
committed by GitHub
parent 79f2c2781a
commit 37f3f9efe1
3 changed files with 108 additions and 1 deletions
+2
View File
@@ -2,6 +2,8 @@
Context compression plugin for [OpenClaw](https://github.com/openclaw/openclaw). Compresses tool outputs, code, logs, and structured data — 70-90% token savings with zero LLM calls.
Tool-call normalization preserves provider metadata, including thought signatures, when restoring assistant turns after compression.
## Install
Recommended one-command setup:
+3
View File
@@ -486,8 +486,11 @@ function normalizeAssistantContent(content: unknown): any[] {
(block.type === "toolCall" || block.type === "tool_use") &&
typeof block.name === "string"
) {
// Legacy input becomes arguments; do not retain an alias that can go stale after compression.
const { input: _legacyInput, ...metadata } = block;
return [
{
...(block.type === "tool_use" ? metadata : block),
type: "toolCall",
id: typeof block.id === "string" ? block.id : "unknown",
name: block.name,
+103 -1
View File
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { agentToOpenAI, normalizeAgentMessages, openAIToAgent, type OpenAIMessage } from "../src/convert";
import { agentToOpenAI, agentToOpenAIIndexed, normalizeAgentMessages, openAIToAgent, restoreAgentMessages, type OpenAIMessage } from "../src/convert";
describe("openAIToAgent", () => {
it("emits toolResult content as blocks so transports can safely filter", () => {
@@ -63,6 +63,108 @@ describe("normalizeAgentMessages", () => {
isError: false,
});
});
it("preserves provider thought signatures on canonical tool calls", () => {
const result = normalizeAgentMessages([
{
role: "assistant",
content: [
{
type: "toolCall",
id: "call_signed",
name: "read",
arguments: { path: "file.ts" },
thoughtSignature: "provider-tool-call-signature",
},
],
},
]);
expect(result[0].content[0].thoughtSignature).toBe("provider-tool-call-signature");
expect(result[0].content[0].arguments).toEqual({ path: "file.ts" });
});
it("normalizes legacy tool inputs without retaining a duplicate alias", () => {
const block = {
type: "tool_use",
name: "read",
input: { path: "file.ts" },
thoughtSignature: "legacy-signature",
providerMetadata: { opaque: true },
};
const result = normalizeAgentMessages([{ role: "assistant", content: [block] }]);
expect(result[0].content[0]).toEqual({
type: "toolCall",
id: "unknown",
name: "read",
arguments: { path: "file.ts" },
thoughtSignature: "legacy-signature",
providerMetadata: { opaque: true },
});
expect(block.input).toEqual({ path: "file.ts" });
expect(block.type).toBe("tool_use");
});
it("keeps existing arguments precedence while removing the legacy alias", () => {
const result = normalizeAgentMessages([
{
role: "assistant",
content: [{ type: "tool_use", name: "read", arguments: null, input: { path: "old.ts" } }],
},
]);
expect(result[0].content[0].arguments).toBeNull();
expect(result[0].content[0]).not.toHaveProperty("input");
});
it("retains opaque extension fields on already canonical tool calls", () => {
const block = {
type: "toolCall",
id: "call_canonical",
name: "read",
arguments: { path: "file.ts" },
input: { extension: "opaque canonical metadata" },
thoughtSignature: "canonical-signature",
providerMetadata: { opaque: true },
};
const result = normalizeAgentMessages([{ role: "assistant", content: [block] }]);
expect(result[0].content[0]).toEqual(block);
});
});
describe("restoreAgentMessages", () => {
it("restores compressed legacy arguments without stale input and preserves metadata", () => {
const block = {
type: "tool_use",
id: "call_legacy",
name: "read",
input: { path: "file.ts", lines: ["long", "original", "payload"] },
thoughtSignature: "legacy-signature",
providerMetadata: { opaque: true },
};
const original = [{ role: "assistant", content: [block] }];
const sent = agentToOpenAIIndexed(original);
const returned = structuredClone(sent);
returned[0].tool_calls![0].function.arguments = '{"path":"file.ts","lines":["short"]}';
const result = restoreAgentMessages(original, sent, returned);
expect(result[0].content[0]).toEqual({
type: "toolCall",
id: "call_legacy",
name: "read",
arguments: { path: "file.ts", lines: ["short"] },
thoughtSignature: "legacy-signature",
providerMetadata: { opaque: true },
});
expect(block.input.lines).toEqual(["long", "original", "payload"]);
expect(agentToOpenAI(result)[0].tool_calls![0].function.arguments)
.toBe('{"path":"file.ts","lines":["short"]}');
});
});
describe("agentToOpenAI", () => {