From 0f2d9abba7e416307ff75284992a6f08a1a7626f Mon Sep 17 00:00:00 2001 From: Diego Rodrigues de Sa e Souza <8016841+diegosouzapw@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:53:22 -0300 Subject: [PATCH] feat(compression): teach the model the CCR retrieve protocol on first marker (#8033) (#8063) --- .../features/8033-ccr-protocol-instruction.md | 1 + docs/compression/COMPRESSION_ENGINES.md | 14 ++ .../services/compression/engines/ccr/index.ts | 7 +- .../engines/ccr/protocolInstruction.ts | 94 +++++++++ tests/unit/ccr-protocol-instruction.test.ts | 184 ++++++++++++++++++ 5 files changed, 299 insertions(+), 1 deletion(-) create mode 100644 changelog.d/features/8033-ccr-protocol-instruction.md create mode 100644 open-sse/services/compression/engines/ccr/protocolInstruction.ts create mode 100644 tests/unit/ccr-protocol-instruction.test.ts diff --git a/changelog.d/features/8033-ccr-protocol-instruction.md b/changelog.d/features/8033-ccr-protocol-instruction.md new file mode 100644 index 0000000000..74ff3ffcd1 --- /dev/null +++ b/changelog.d/features/8033-ccr-protocol-instruction.md @@ -0,0 +1 @@ +- Teach the model the CCR retrieve protocol (marker → `omniroute_ccr_retrieve`, verbatim 24-char hash, `dedup:ref` look-back) on the first marker, gated on MCP-tool capability (#8033) diff --git a/docs/compression/COMPRESSION_ENGINES.md b/docs/compression/COMPRESSION_ENGINES.md index 7abe00d658..2bd5a5b322 100644 --- a/docs/compression/COMPRESSION_ENGINES.md +++ b/docs/compression/COMPRESSION_ENGINES.md @@ -57,6 +57,20 @@ structural engines (used by stacked pipelines, the playground, and tests): | ionizer | `ionizer` | Head/middle/tail row sampling for very large homogeneous blocks, storing the elided middle as a CCR content-addressed reference. | | session-dedup | `session-dedup` | Content-addressed cross-turn deduplication (TokenMizer-inspired): elides text already seen in earlier turns of the same session. | +**CCR retrieve-protocol instruction (#8033):** the first time CCR replaces ≥1 block in a +request, the engine prepends a single, idempotent `system` message (leading with the +`[CCR protocol]` sentinel) teaching the caller the marker → tool contract: what a +`[CCR retrieve hash=<24hex> chars=N]` marker means, that the hash must be copied verbatim +(all 24 hex characters — mis-copied hashes are the likely cause of "block not found" +misses), and that a `[dedup:ref sha=...]` marker means "look back in history", not "call the +tool". The note is injected **only when the caller's advertised `tools[]` proves it can +actually reach `omniroute_ccr_retrieve`** (`callerSupportsCcrRetrieve()` in +`open-sse/services/compression/engines/ccr/protocolInstruction.ts`) — a plain +OpenAI-compatible caller without that tool never receives an instruction to call something +it cannot reach. Idempotency is enforced by scanning the message history for the sentinel +before injecting, so multi-turn requests (which replay prior messages) do not stack the +note once per turn. + ## Caveman Caveman mode focuses on semantic condensation of normal prose: diff --git a/open-sse/services/compression/engines/ccr/index.ts b/open-sse/services/compression/engines/ccr/index.ts index a5263bca8b..476d9b37b0 100644 --- a/open-sse/services/compression/engines/ccr/index.ts +++ b/open-sse/services/compression/engines/ccr/index.ts @@ -39,6 +39,7 @@ import crypto from "node:crypto"; import { createCompressionStats } from "../../stats.ts"; import { queryBlock, type CcrQuery } from "./ccrQuery.ts"; +import { injectCcrProtocolInstruction } from "./protocolInstruction.ts"; import type { CompressionEngine, CompressionEngineApplyOptions, @@ -759,7 +760,11 @@ export const ccrEngine: CompressionEngine = { return { body, compressed: false, stats: null }; } - const newBody: Record = { ...body, messages: newMessages }; + // #8033: teach MCP-capable callers the marker → omniroute_ccr_retrieve contract + // (once per session; never told to non-MCP callers who cannot reach the tool). + const messagesWithProtocol = injectCcrProtocolInstruction(newMessages, body); + + const newBody: Record = { ...body, messages: messagesWithProtocol }; const durationMs = Math.round(performance.now() - start); const stats = createCompressionStats( body, diff --git a/open-sse/services/compression/engines/ccr/protocolInstruction.ts b/open-sse/services/compression/engines/ccr/protocolInstruction.ts new file mode 100644 index 0000000000..7882a60b23 --- /dev/null +++ b/open-sse/services/compression/engines/ccr/protocolInstruction.ts @@ -0,0 +1,94 @@ +/** + * CCR retrieve-protocol instruction (#8033) + * + * The CCR engine replaces large blocks of text with a bare + * `[CCR retrieve hash=<24hex> chars=N]` marker (see `index.ts`). A caller that has + * never been told what that marker means has no way to recover the original + * content — it can only call `omniroute_ccr_retrieve` if it (a) knows the tool + * exists and (b) copies the 24-hex hash verbatim. + * + * This module injects a single, idempotent `system` message the first time a + * request carries a CCR marker, teaching the model the marker → tool contract — + * but ONLY when the caller's advertised `tools[]` proves it can actually reach + * `omniroute_ccr_retrieve` (an MCP-capable caller). Plain OpenAI-compatible + * callers that cannot reach the tool must never be told to call it. + */ + +const CCR_RETRIEVE_TOOL_NAME = "omniroute_ccr_retrieve"; + +/** Leading marker that identifies the injected instruction (also the idempotency sentinel). */ +export const CCR_PROTOCOL_MARKER_SENTINEL = "[CCR protocol]"; + +export const CCR_PROTOCOL_INSTRUCTION = `${CCR_PROTOCOL_MARKER_SENTINEL} This conversation uses content-compression-retrieve (CCR). When you see a marker like \`[CCR retrieve hash=<24hex> chars=N]\` in a message, it means the full original text (N characters) was stored and replaced with this marker to save space — call the \`${CCR_RETRIEVE_TOOL_NAME}\` tool with that hash to get the original text back verbatim. Copy the hash EXACTLY as written — all 24 hexadecimal characters, never truncated, abbreviated, or reformatted — a single wrong character will make the retrieval fail. If you instead see a marker like \`[dedup:ref sha=...]\`, it means that content already appeared earlier in this conversation — look back in the message history for it; do NOT call ${CCR_RETRIEVE_TOOL_NAME} for a dedup reference.`; + +type ToolLike = { + type?: unknown; + name?: unknown; + function?: { name?: unknown } | null; +}; + +/** + * Scan a request body's `tools[]` for the CCR retrieve tool name, across the + * three shapes seen in the wild: OpenAI-nested (`{type:"function", + * function:{name}}`), flat (`{name}`), and Claude (`{name}`). A non-array or + * absent `tools` field means the caller advertised no tools at all → `false`. + */ +export function callerSupportsCcrRetrieve(body: Record): boolean { + const tools = body["tools"]; + if (!Array.isArray(tools)) return false; + + return tools.some((tool) => { + const t = tool as ToolLike; + const flatName = typeof t?.name === "string" ? t.name : undefined; + const nestedName = typeof t?.function?.name === "string" ? t.function.name : undefined; + return flatName === CCR_RETRIEVE_TOOL_NAME || nestedName === CCR_RETRIEVE_TOOL_NAME; + }); +} + +type MessageWithContent = { + role?: unknown; + content?: unknown; +}; + +function messageContainsSentinel(message: MessageWithContent): boolean { + const content = message?.content; + if (typeof content === "string") return content.includes(CCR_PROTOCOL_MARKER_SENTINEL); + if (Array.isArray(content)) { + return content.some( + (part) => + part && + typeof part === "object" && + typeof (part as Record)["text"] === "string" && + ((part as Record)["text"] as string).includes( + CCR_PROTOCOL_MARKER_SENTINEL + ) + ); + } + return false; +} + +/** + * Prepend the CCR protocol instruction as a single leading `system` message, + * but only when: + * - the caller can actually reach `omniroute_ccr_retrieve` (see + * `callerSupportsCcrRetrieve`), and + * - the message history does not already carry the sentinel (idempotent — + * multi-turn requests replay prior messages, so without this check the + * note would stack once per turn). + * + * Otherwise returns `messages` unchanged. + */ +export function injectCcrProtocolInstruction( + messages: T[], + body: Record +): T[] { + if (!callerSupportsCcrRetrieve(body)) return messages; + if (messages.some((message) => messageContainsSentinel(message))) return messages; + + const instructionMessage = { + role: "system", + content: CCR_PROTOCOL_INSTRUCTION, + } as unknown as T; + + return [instructionMessage, ...messages]; +} diff --git a/tests/unit/ccr-protocol-instruction.test.ts b/tests/unit/ccr-protocol-instruction.test.ts new file mode 100644 index 0000000000..e95f8b94d5 --- /dev/null +++ b/tests/unit/ccr-protocol-instruction.test.ts @@ -0,0 +1,184 @@ +/** + * TDD tests for the CCR retrieve-protocol instruction injection (#8033). + * Run: node --import tsx/esm --test tests/unit/ccr-protocol-instruction.test.ts + * + * The CCR engine replaces large blocks of text with a bare + * `[CCR retrieve hash=<24hex> chars=N]` marker that the model has never been + * taught to act on. This suite verifies the injected system-note instruction: + * present exactly once for MCP-capable callers, absent for plain callers. + */ + +import { describe, it, before } from "node:test"; +import assert from "node:assert/strict"; + +import { ccrEngine, resetCcrStore } from "../../open-sse/services/compression/engines/ccr/index.ts"; +import { + CCR_PROTOCOL_MARKER_SENTINEL, + callerSupportsCcrRetrieve, + injectCcrProtocolInstruction, +} from "../../open-sse/services/compression/engines/ccr/protocolInstruction.ts"; +import { + registerBuiltinCompressionEngines, + getCompressionEngine, +} from "../../open-sse/services/compression/index.ts"; + +// ─── helpers ────────────────────────────────────────────────────────────────── + +const LARGE_TEXT = `This is a large block of content that should trigger CCR compression. +It contains multiple lines and substantial text. +The CCR engine compresses large contiguous blocks of text. +Replacing them with a content-addressed retrieve marker. +This allows the model to retrieve the verbatim content on demand. +Using the retrieve MCP tool with the hash from the marker. +The block must be large enough to exceed the minimum threshold. +Default minimum is 600 characters, so this block is crafted accordingly. +We need to be thorough and ensure the block is truly large enough. +This is line ten and still counting to make the block big enough.`; + +const SMALL_TEXT = "Short content that should NOT be compressed."; + +const RETRIEVE_TOOL_OPENAI = { type: "function", function: { name: "omniroute_ccr_retrieve" } }; +const RETRIEVE_TOOL_FLAT = { name: "omniroute_ccr_retrieve" }; +const RETRIEVE_TOOL_CLAUDE = { name: "omniroute_ccr_retrieve", input_schema: {} }; + +type Msg = { role: string; content: string }; + +function makeBody(messages: Msg[], tools?: unknown[]): Record { + const body: Record = { model: "gpt-4", messages }; + if (tools) body["tools"] = tools; + return body; +} + +// ─── tests ──────────────────────────────────────────────────────────────────── + +describe("ccr protocol instruction (#8033)", () => { + before(() => { + resetCcrStore(); + registerBuiltinCompressionEngines(); + }); + + it("is registered and retrievable by id", () => { + const engine = getCompressionEngine("ccr"); + assert.ok(engine, "getCompressionEngine('ccr') must return the engine"); + }); + + it("MCP-capable caller + a replaced block → instruction present exactly once as a leading system message", () => { + resetCcrStore(); + const body = makeBody([{ role: "user", content: LARGE_TEXT }], [RETRIEVE_TOOL_OPENAI]); + const result = ccrEngine.apply(body); + + assert.equal(result.compressed, true, "large block should compress"); + const messages = result.body["messages"] as Array<{ role: string; content: unknown }>; + + assert.equal(messages[0].role, "system", "instruction must be a leading system message"); + assert.ok( + typeof messages[0].content === "string" && + messages[0].content.startsWith(CCR_PROTOCOL_MARKER_SENTINEL), + "leading system message must start with the CCR protocol sentinel" + ); + + const occurrences = messages.filter( + (m) => typeof m.content === "string" && m.content.includes(CCR_PROTOCOL_MARKER_SENTINEL) + ); + assert.equal(occurrences.length, 1, "instruction must be present exactly once"); + }); + + it("plain OpenAI-compatible caller (no tools) → NO instruction at all", () => { + resetCcrStore(); + const body = makeBody([{ role: "user", content: LARGE_TEXT }]); + const result = ccrEngine.apply(body); + + assert.equal(result.compressed, true, "large block should still compress"); + const messages = result.body["messages"] as Array<{ role: string; content: unknown }>; + + assert.equal(messages.length, 1, "no system message should be injected"); + assert.ok( + messages.every( + (m) => typeof m.content !== "string" || !m.content.includes(CCR_PROTOCOL_MARKER_SENTINEL) + ), + "no message may contain the CCR protocol sentinel" + ); + }); + + it("caller with tools[] not advertising the retrieve tool → NO instruction", () => { + resetCcrStore(); + const otherTool = { type: "function", function: { name: "some_other_tool" } }; + const body = makeBody([{ role: "user", content: LARGE_TEXT }], [otherTool]); + const result = ccrEngine.apply(body); + + const messages = result.body["messages"] as Array<{ role: string; content: unknown }>; + assert.equal(messages.length, 1, "no system message should be injected"); + }); + + it("replacedCount === 0 → body untouched (no instruction, compressed:false)", () => { + resetCcrStore(); + const body = makeBody([{ role: "user", content: SMALL_TEXT }], [RETRIEVE_TOOL_OPENAI]); + const result = ccrEngine.apply(body); + + assert.equal(result.compressed, false, "small text should not compress"); + assert.equal(result.body, body, "body must be returned unchanged when nothing was replaced"); + }); + + it("idempotency: a body whose history already carries the sentinel is not injected twice", () => { + resetCcrStore(); + const alreadyInstructed: Msg = { + role: "system", + content: `${CCR_PROTOCOL_MARKER_SENTINEL} already told once`, + }; + const body = makeBody( + [alreadyInstructed, { role: "user", content: LARGE_TEXT }], + [RETRIEVE_TOOL_OPENAI] + ); + const result = ccrEngine.apply(body); + + const messages = result.body["messages"] as Array<{ role: string; content: unknown }>; + const occurrences = messages.filter( + (m) => typeof m.content === "string" && m.content.includes(CCR_PROTOCOL_MARKER_SENTINEL) + ); + assert.equal(occurrences.length, 1, "sentinel must not be injected a second time"); + }); + + it("instruction text contains the tool name, the marker shape, and the verbatim-24-char warning", () => { + resetCcrStore(); + const body = makeBody([{ role: "user", content: LARGE_TEXT }], [RETRIEVE_TOOL_OPENAI]); + const result = ccrEngine.apply(body); + const messages = result.body["messages"] as Array<{ role: string; content: unknown }>; + const instruction = messages[0].content as string; + + assert.ok(instruction.includes("omniroute_ccr_retrieve"), "must mention the tool name"); + assert.ok( + instruction.includes("[CCR retrieve hash=<24hex> chars=N]"), + "must show the marker shape" + ); + assert.match( + instruction, + /verbatim|exact/i, + "must stress verbatim/exact copying of the hash" + ); + assert.match(instruction, /24/, "must mention the 24-character length of the hash"); + assert.ok(instruction.includes("dedup:ref"), "must mention the dedup:ref contract"); + }); + + it("recognizes all three tools[] shapes: OpenAI nested, flat, Claude", () => { + assert.equal(callerSupportsCcrRetrieve({ tools: [RETRIEVE_TOOL_OPENAI] }), true, "OpenAI nested shape"); + assert.equal(callerSupportsCcrRetrieve({ tools: [RETRIEVE_TOOL_FLAT] }), true, "flat shape"); + assert.equal(callerSupportsCcrRetrieve({ tools: [RETRIEVE_TOOL_CLAUDE] }), true, "Claude shape"); + assert.equal(callerSupportsCcrRetrieve({ tools: [] }), false, "empty tools array"); + assert.equal(callerSupportsCcrRetrieve({}), false, "absent tools field"); + assert.equal( + callerSupportsCcrRetrieve({ tools: "not-an-array" }), + false, + "non-array tools field" + ); + }); + + it("injectCcrProtocolInstruction is a pure helper usable directly", () => { + const messages: Msg[] = [{ role: "user", content: "hi" }]; + const withInstruction = injectCcrProtocolInstruction(messages, { tools: [RETRIEVE_TOOL_FLAT] }); + assert.equal(withInstruction.length, 2); + assert.equal(withInstruction[0].role, "system"); + + const withoutInstruction = injectCcrProtocolInstruction(messages, {}); + assert.equal(withoutInstruction, messages, "unchanged reference when caller cannot retrieve"); + }); +});