Merge pull request #4715 from Mako-L/2026-10-25_system-position-heal

[PR] kernel: heal system positions on the final Anthropic wire array (#4570)
This commit is contained in:
ranxianglei
2026-11-10 00:01:08 +08:00
committed by GitHub
8 changed files with 292 additions and 10 deletions
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "acp-kernel",
"version": "0.0.189",
"version": "0.0.190",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "acp-kernel",
"version": "0.0.189",
"version": "0.0.190",
"license": "MIT",
"devDependencies": {
"@types/node": "^22.0.0",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "acp-kernel",
"version": "0.0.189",
"version": "0.0.190",
"description": "Framework-agnostic context-compression engine (model-driven, 3-tier LSM). Pure core: no host dependency.",
"license": "MIT",
"author": "ranxianglei",
+12
View File
@@ -499,6 +499,18 @@ export function insertBeforeTrailingSystemRun(
return [...messages.slice(0, i), ...additions, ...messages.slice(i)];
}
/** #4570: the position backstop as a standalone pass over a FINAL Anthropic
* messages array — hosts that append messages after coreToAnthropic (notes,
* nudges, side-call prompts) run it on the array they actually send. Same
* heal as coreToAnthropic's internal pass (#5438); fresh objects only. */
export function healAnthropicSystemPositions(
messages: readonly AnthropicWireMessage[],
): AnthropicWireMessage[] {
const out = [...messages];
healIllegalSystemPositions(out);
return out;
}
export function coreToAnthropic(
messages: BiliMessage[],
cacheControls?: Map<string, unknown>,
@@ -0,0 +1,206 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import {
coreToAnthropic,
healAnthropicSystemPositions,
} from "../src/wire/anthropic.js";
import type {
AnthropicSystemMessage,
AnthropicWireMessage,
} from "../src/wire/anthropic.js";
import type { BiliMessage } from "../src/wire/bili-message.js";
// #4570: Anthropic's mid-conversation system rule has two halves, and
// production 400s hit both:
// "role 'system' must precede an 'assistant' message or end the array"
// — a legal trailing system left by coreToAnthropic, then host notes /
// nudges / the retrieval note appended after it.
// "role 'system' must follow a 'user' message or an 'assistant' message
// ending in a server tool result"
// — a fold (compress-loop re-request) removes the user turn before a
// never-fold sidecar system, leaving it right after an assistant.
// The two-sided heal lives in coreToAnthropic (#5438); #4570 adds the
// FINAL-array backstop (healAnthropicSystemPositions) for hosts that append
// after coreToAnthropic returned. Demotion re-voices to user with tool-delta
// blocks stripped (WC-022); user-visible text is never dropped.
function sys(content: AnthropicSystemMessage["content"]): AnthropicSystemMessage {
return { role: "system", content };
}
function isDirectiveOnly(m: AnthropicWireMessage): boolean {
return (
m.role === "system" &&
Array.isArray(m.content) &&
m.content.length === 0 &&
(m as { output_config?: unknown }).output_config != null
);
}
// Mirrors the kernel's #5438 contract: an array start (no predecessor) is
// legal by contract; the tool-result family is matched by suffix (server-tool
// results ride inside assistant messages on the real wire).
function legalPredecessor(m: AnthropicWireMessage | undefined): boolean {
if (!m) return true;
if (m.role === "user") return true;
if (m.role !== "assistant" || !Array.isArray(m.content)) return false;
const last = m.content[m.content.length - 1] as { type?: unknown } | undefined;
return typeof last?.type === "string" && last.type.endsWith("tool_result");
}
/** Every violation of either half of the rule, as Anthropic reports it. */
function violations(messages: AnthropicWireMessage[]): string[] {
const bad: string[] = [];
messages.forEach((m, i) => {
if (m.role !== "system" || isDirectiveOnly(m)) return;
let p = i - 1;
while (p >= 0 && messages[p]!.role === "system") p--;
let k = i + 1;
while (k < messages.length && messages[k]!.role === "system") k++;
if (!legalPredecessor(messages[p])) bad.push(`messages.${i}: must follow`);
const next = messages[k];
if (next && next.role !== "assistant") bad.push(`messages.${i}: must precede`);
});
return bad;
}
function texts(messages: AnthropicWireMessage[]): string[] {
const out: string[] = [];
for (const m of messages) {
if (typeof m.content === "string") out.push(m.content);
else for (const b of m.content as { type?: string; text?: string }[]) if (b.type === "text" && b.text) out.push(b.text);
}
return out;
}
const user = (id: string, text: string): BiliMessage => ({ id, role: "user", contentType: "text", text });
const assistant = (id: string, text: string): BiliMessage => ({ id, role: "assistant", contentType: "text", text });
const sidecar = (id: string, raw: AnthropicSystemMessage): BiliMessage => ({
id,
role: "system",
contentType: "text",
text: texts([raw]).join("\n"),
rawAnthropicMessage: raw,
});
const TOOL_ADDITION = {
type: "tool_addition",
tool: { type: "tool_definition", definition: { name: "t", input_schema: { type: "object" } } },
};
// --- "must precede": the #4570 nudge-turn shape ----------------------------
test("#4570 shape: a note appended after a trailing system is healed on the final array", () => {
const wire = coreToAnthropic([
user("u1", "q1"),
assistant("a1", "a1"),
user("u2", "q2"),
sidecar("s1", sys([{ type: "text", text: "<system-reminder>env</system-reminder>" }])),
]);
assert.deepEqual(violations(wire), [], "coreToAnthropic output is legal on its own");
const sent = healAnthropicSystemPositions([
...wire,
{ role: "user", content: "[ACP] nudge: compress now" },
{ role: "user", content: "[retrieval] pending note" },
]);
assert.deepEqual(violations(sent), []);
assert.deepEqual(texts(sent), ["q1", "a1", "q2", "<system-reminder>env</system-reminder>", "[ACP] nudge: compress now", "[retrieval] pending note"]);
assert.equal(sent.length, 6);
});
test("#4570 shape: a trailing tool-delta run before a note keeps the text and drops tool deltas", () => {
const sent = healAnthropicSystemPositions([
{ role: "user", content: "q" },
sys([{ type: "text", text: "tools updated" }, TOOL_ADDITION] as never),
sys([TOOL_ADDITION] as never),
{ role: "user", content: "nudge" },
]);
assert.deepEqual(violations(sent), []);
assert.deepEqual(texts(sent), ["q", "tools updated", "nudge"]);
assert.ok(!JSON.stringify(sent).includes("tool_addition"));
});
// --- "must follow": a system right after an assistant -----------------------
test("must-follow shape: a sidecar system between two assistants is re-voiced", () => {
const wire = coreToAnthropic([
user("u1", "q1"),
assistant("a1", "a1"),
sidecar("s1", sys([{ type: "text", text: "mid-session update" }])),
assistant("a2", "a2"),
user("u2", "q2"),
]);
assert.deepEqual(violations(wire), []);
assert.deepEqual(texts(wire), ["q1", "a1", "mid-session update", "a2", "q2"]);
});
test("must-follow shape: a system after an assistant is re-voiced in place", () => {
const sent = healAnthropicSystemPositions([
{ role: "user", content: "q1" },
{ role: "assistant", content: [{ type: "tool_use", id: "t1", name: "bash", input: {} }] },
sys([{ type: "text", text: "tools updated" }, TOOL_ADDITION] as never),
{ role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "ok" }] },
{ role: "assistant", content: [{ type: "text", text: "done" }] },
]);
assert.deepEqual(violations(sent), []);
assert.equal(sent[2]!.role, "user", "demoted in place (#5438)");
assert.ok(JSON.stringify(sent).includes("tools updated"), "text kept");
assert.ok(!JSON.stringify(sent).includes("tool_addition"), "WC-022: delta stripped on demotion");
});
test("must-follow shape: a run of systems after an assistant is demoted in order", () => {
const sent = healAnthropicSystemPositions([
{ role: "user", content: "q1" },
{ role: "assistant", content: [{ type: "text", text: "a1" }] },
sys("first"),
sys("second"),
{ role: "user", content: "q2" },
]);
assert.deepEqual(violations(sent), []);
assert.deepEqual(texts(sent), ["q1", "a1", "first", "second", "q2"]);
});
test("must-follow shape: a trailing system after an assistant is re-voiced; a leading one is untouched", () => {
const trailing = healAnthropicSystemPositions([
{ role: "user", content: "q1" },
{ role: "assistant", content: [{ type: "text", text: "a1" }] },
sys("late update"),
]);
assert.deepEqual(violations(trailing), []);
assert.deepEqual(texts(trailing), ["q1", "a1", "late update"]);
const leading = coreToAnthropic([
sidecar("s0", sys("early")),
assistant("a0", "ok"),
user("u1", "q1"),
]);
assert.deepEqual(violations(leading), []);
assert.equal(leading[0]!.role, "system", "array start is legal by contract (#5438)");
assert.deepEqual(texts(leading), ["early", "ok", "q1"]);
});
// --- negative: legal layouts stay verbatim ----------------------------------
test("legal layouts round-trip verbatim", () => {
const serverResult: AnthropicWireMessage = {
role: "assistant",
content: [
{ type: "server_tool_use", id: "srvtoolu_1", name: "web_search", input: {} },
{ type: "web_search_tool_result", tool_use_id: "srvtoolu_1", content: [] },
] as never,
};
const directive = { role: "system", content: [], output_config: { effort: "high" } } as unknown as AnthropicWireMessage;
const u = (t: string): AnthropicWireMessage => ({ role: "user", content: t });
const a = (t: string): AnthropicWireMessage => ({ role: "assistant", content: [{ type: "text", text: t }] });
const layouts: AnthropicWireMessage[][] = [
[u("q"), sys("s"), a("a"), u("q2")],
[u("q"), a("a"), u("q2"), sys("s")],
[u("q"), sys("s1"), sys("s2"), a("a")],
[u("q"), directive, sys("s"), a("a")],
[u("q"), a("a"), directive, a("a2"), u("q2")],
[u("q"), serverResult, sys("s"), a("a")],
];
for (const layout of layouts) {
assert.deepEqual(violations(layout), []);
assert.deepEqual(healAnthropicSystemPositions(layout), layout);
}
});
+1 -1
View File
@@ -50,7 +50,7 @@
},
"kernel": {
"name": "acp-kernel",
"version": "0.0.189",
"version": "0.0.190",
"dev": true,
"license": "MIT",
"devDependencies": {
+2 -2
View File
@@ -1,5 +1,5 @@
import type { CoreMessage } from "acp-kernel";
import { coreToAnthropic, type AnthropicRequestBody } from "acp-kernel/wire";
import { coreToAnthropic, healAnthropicSystemPositions, type AnthropicRequestBody } from "acp-kernel/wire";
import { dedupeAdjacentOutputConfig } from "../dedupe-adjacent-output-config.js";
import { appendSystemText, declaredInclusiveFromUsage } from "../util.js";
import { stampAnthropicSystemCacheControl } from "./cache-control.js";
@@ -317,7 +317,7 @@ export function createAnthropicAdapter(requestBody: Record<string, unknown>, ori
const system = originalSystem !== undefined ? appendSystemText(systemPrompt, originalSystem) : systemPrompt;
const stamped = cacheMarks ? stampAnthropicSystemCacheControl(system) : system;
const withNotes = notes && notes.length > 0
? [...messages, ...notes.map((text) => ({ role: "user" as const, content: text }))]
? healAnthropicSystemPositions([...messages, ...notes.map((text) => ({ role: "user" as const, content: text }))])
: messages;
return { ...body, system: stamped, messages: withNotes };
},
+14 -4
View File
@@ -1,7 +1,7 @@
import http from "node:http";
import type { CompressionCore, Config, CoreMessage, NudgeDecision, PackSurface, Prompts } from "acp-kernel";
import { renderNudgeText, viableRanges } from "acp-kernel";
import { anthropicToCore, buildSystem, coreToAnthropic, extractSystem, insertBeforeTrailingSystemRun, type AnthropicRequestBody, type AnthropicWireMessage, type BiliMessage } from "acp-kernel/wire";
import { anthropicToCore, buildSystem, coreToAnthropic, extractSystem, healAnthropicSystemPositions, insertBeforeTrailingSystemRun, type AnthropicRequestBody, type AnthropicWireMessage, type BiliMessage } from "acp-kernel/wire";
import { rewriteInboundThreadContinue } from "./thread-tracking.js";
import { captureThreadsTurn, estimateThreadsTokens, isThreadsBody, threadsReforgeEnabled } from "./threads-lane.js";
import type { CompressReasoningConfig } from "../reasoning-drop.js";
@@ -535,7 +535,9 @@ export async function prepareAnthropic(
const ranges = turn.nudge.compressibleRanges ?? [];
// [#5688] the side call shares the main request's upstream —
// un-deduped rebuiltMessages would 400 the decision too.
const sideBody: Record<string, unknown> = { ...parsed, messages: [...dedupeAdjacentOutputConfig(rebuiltMessages), { role: "user", content: buildDecisionPrompt(ranges) }], system: systemOut, tools: toolsOut, stream: false, max_tokens: decide.maxTokens };
// [#4570] and the side array must obey the system-position rule
// on the array actually sent, which is exactly this one.
const sideBody: Record<string, unknown> = { ...parsed, messages: healAnthropicSystemPositions([...dedupeAdjacentOutputConfig(rebuiltMessages), { role: "user", content: buildDecisionPrompt(ranges) }]), system: systemOut, tools: toolsOut, stream: false, max_tokens: decide.maxTokens };
delete sideBody.prompt_cache_key;
stripDecisionReasoningFields("anthropic", sideBody);
const outcome = await runNudgeDecision({ req, opts, protocol: "anthropic", sideBody, session, log });
@@ -622,8 +624,16 @@ export async function prepareAnthropic(
if (dedupedMessages !== rebuiltMessages) {
log("warn", `[${sessionId}] adjacent-output-config: collapsed duplicate effort directive(s) after fold reconstruction (#5688)`);
}
warnAnthropicThinkingPairs(parsed.messages, dedupedMessages, log, sessionId);
const rebuilt: AnthropicRequestBody = { ...parsed, messages: dedupedMessages, system: systemOut, tools: toolsOut };
// #4570: notes, nudges and the retrieval note append AFTER coreToAnthropic's
// heal, so the position rule is enforced again on the array actually sent.
// This is the LAST transform: the rule is judged on the exact array the
// upstream receives, with #5604's tail nudge and #5688's collapse in place.
// The pass only re-voices illegal systems in place (never reorders), so the
// trailing-user tail #5604 established stays last.
const healedMessages = healAnthropicSystemPositions(dedupedMessages);
warnAnthropicThinkingPairs(parsed.messages, healedMessages, log, sessionId);
const rebuilt: AnthropicRequestBody = { ...parsed, messages: healedMessages, system: systemOut, tools: toolsOut };
// prompt_cache_key is the omp plugin's session id stamped for the proxy's
// identity chain (#268), not part of the Anthropic Messages API — strip it
// so the real upstream never sees a field it doesn't know.
@@ -0,0 +1,54 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import type { CoreMessage } from "acp-kernel";
import { createAnthropicAdapter } from "../src/loop/index.ts";
import { VALIDATORS } from "./wire-contract-fakes.ts";
// #4570 / WC-023: the compress-loop adapter appends system notes AFTER
// coreToAnthropic's position heal. A trailing client system (legal on its
// own) then sits before a user note — Anthropic 400s "role 'system' must
// precede an 'assistant' message or end the array". The re-request body must
// obey both halves of the rule on the array actually sent.
const BODY = { model: "claude", messages: [], stream: true, max_tokens: 10 };
function sidecar(id: string, text: string): CoreMessage {
return { id, role: "system", contentType: "text", text, rawAnthropicMessage: { role: "system", content: [{ type: "text", text }] } } as CoreMessage;
}
test("#4570: compress-loop notes after a trailing system leave a legal wire array", () => {
const adapter = createAnthropicAdapter(BODY, undefined, ["[bili] retrieval note"]);
const body = adapter.buildRequest([
{ id: "u1", role: "user", contentType: "text", text: "q1" },
{ id: "a1", role: "assistant", contentType: "text", text: "a1" },
{ id: "u2", role: "user", contentType: "text", text: "q2" },
sidecar("s1", "<system-reminder>env</system-reminder>"),
] as CoreMessage[], "sys", BODY) as { messages: { role: string; content: unknown }[] };
assert.deepEqual(VALIDATORS.anthropic(body).filter((v) => v.startsWith("WC-023")), []);
const wire = JSON.stringify(body.messages);
assert.ok(wire.includes("<system-reminder>env</system-reminder>"), "system text kept");
assert.ok(wire.includes("[bili] retrieval note"), "note kept");
});
test("#4570 must-follow: a post-fold sidecar after an assistant is healed on the re-request", () => {
const adapter = createAnthropicAdapter(BODY);
const body = adapter.buildRequest([
{ id: "anchor", role: "user", contentType: "text", text: "[Compressed conversation section] x" },
{ id: "a1", role: "assistant", contentType: "text", text: "a1" },
sidecar("s1", "tools updated"),
{ id: "a2", role: "assistant", contentType: "text", text: "a2" },
{ id: "u2", role: "user", contentType: "text", text: "q2" },
] as CoreMessage[], "sys", BODY) as { messages: { role: string; content: unknown }[] };
assert.deepEqual(VALIDATORS.anthropic(body).filter((v) => v.startsWith("WC-023")), []);
assert.ok(JSON.stringify(body.messages).includes("tools updated"));
});
test("#4570 negative: a legal trailing system with no notes stays a system", () => {
const adapter = createAnthropicAdapter(BODY);
const body = adapter.buildRequest([
{ id: "u1", role: "user", contentType: "text", text: "q1" },
sidecar("s1", "env"),
] as CoreMessage[], "sys", BODY) as { messages: { role: string; content: unknown }[] };
assert.equal(body.messages[body.messages.length - 1]!.role, "system");
assert.deepEqual(VALIDATORS.anthropic(body).filter((v) => v.startsWith("WC-023")), []);
});