feat(compression): teach the model the CCR retrieve protocol on first marker (#8033) (#8063)

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)

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:

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<string, unknown> = { ...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<string, unknown> = { ...body, messages: messagesWithProtocol };
     const durationMs = Math.round(performance.now() - start);
     const stats = createCompressionStats(
       body,

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<string, unknown>): 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<string, unknown>)["text"] === "string" &&
+        ((part as Record<string, unknown>)["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<T extends MessageWithContent>(
+  messages: T[],
+  body: Record<string, unknown>
+): 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];
+}

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<string, unknown> {
+  const body: Record<string, unknown> = { 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");
+  });
+});