feat: migrate compress to injected ID boundaries

Author: Tarquinen

README.md

@@ -30,7 +30,7 @@ For model-facing behavior (prompts and tool calls), this capability is always ad
 
 ### Tool
 
-**Compress** — Exposes a single `compress` tool with one method: match a conversation range using `startString` and `endString`, then replace it with a technical summary.
+**Compress** — Exposes a single `compress` tool with one method: select a conversation range using injected `startId` and `endId` (`mNNNN` or `bN`), then replace it with a technical summary.
 
 The model can use that same method at different scales: tiny ranges for noise cleanup, focused ranges for preserving key findings, and full chapters for completed work.
 

lib/hooks.ts

@@ -1,9 +1,10 @@
 import type { SessionState, WithParts } from "./state"
 import type { Logger } from "./logger"
 import type { PluginConfig } from "./config"
+import { assignMessageRefs } from "./message-ids"
 import { syncToolCache } from "./state/tool-cache"
 import { deduplicate, supersedeWrites, purgeErrors } from "./strategies"
-import { prune, insertCompressToolContext } from "./messages"
+import { prune, insertCompressToolContext, insertMessageIdContext } from "./messages"
 import { buildToolIdList, isIgnoredUserMessage } from "./messages/utils"
 import { checkSession } from "./state"
 import { renderSystemPrompt } from "./prompts"
@@ -104,6 +105,8 @@ export function createChatMessageTransformHandler(
 
         cacheSystemPromptTokens(state, output.messages)
 
+        assignMessageRefs(state, output.messages)
+
         syncToolCache(state, config, logger, output.messages)
         buildToolIdList(state, output.messages)
 
@@ -113,6 +116,8 @@ export function createChatMessageTransformHandler(
 
         prune(state, logger, config, output.messages)
 
+        insertMessageIdContext(state, output.messages)
+
         insertCompressToolContext(state, config, logger, output.messages)
 
         applyPendingManualTriggerPrompt(state, output.messages, logger)

lib/message-ids.ts

@@ -0,0 +1,132 @@
+import type { SessionState, WithParts } from "./state"
+
+const MESSAGE_REF_REGEX = /^m(\d{4})$/
+const BLOCK_REF_REGEX = /^b([1-9]\d*)$/
+
+const MESSAGE_REF_WIDTH = 4
+const MESSAGE_REF_MIN_INDEX = 0
+export const MESSAGE_REF_MAX_INDEX = 9999
+
+export type ParsedBoundaryId =
+    | {
+          kind: "message"
+          ref: string
+          index: number
+      }
+    | {
+          kind: "compressed-block"
+          ref: string
+          blockId: number
+      }
+
+export function formatMessageRef(index: number): string {
+    if (
+        !Number.isInteger(index) ||
+        index < MESSAGE_REF_MIN_INDEX ||
+        index > MESSAGE_REF_MAX_INDEX
+    ) {
+        throw new Error(
+            `Message ID index out of bounds: ${index}. Supported range is 0-${MESSAGE_REF_MAX_INDEX}.`,
+        )
+    }
+    return `m${index.toString().padStart(MESSAGE_REF_WIDTH, "0")}`
+}
+
+export function formatBlockRef(blockId: number): string {
+    if (!Number.isInteger(blockId) || blockId < 1) {
+        throw new Error(`Invalid block ID: ${blockId}`)
+    }
+    return `b${blockId}`
+}
+
+export function parseMessageRef(ref: string): number | null {
+    const normalized = ref.trim().toLowerCase()
+    const match = normalized.match(MESSAGE_REF_REGEX)
+    if (!match) {
+        return null
+    }
+    const index = Number.parseInt(match[1], 10)
+    return Number.isInteger(index) ? index : null
+}
+
+export function parseBlockRef(ref: string): number | null {
+    const normalized = ref.trim().toLowerCase()
+    const match = normalized.match(BLOCK_REF_REGEX)
+    if (!match) {
+        return null
+    }
+    const id = Number.parseInt(match[1], 10)
+    return Number.isInteger(id) ? id : null
+}
+
+export function parseBoundaryId(id: string): ParsedBoundaryId | null {
+    const normalized = id.trim().toLowerCase()
+    const messageIndex = parseMessageRef(normalized)
+    if (messageIndex !== null) {
+        return {
+            kind: "message",
+            ref: formatMessageRef(messageIndex),
+            index: messageIndex,
+        }
+    }
+
+    const blockId = parseBlockRef(normalized)
+    if (blockId !== null) {
+        return {
+            kind: "compressed-block",
+            ref: formatBlockRef(blockId),
+            blockId,
+        }
+    }
+
+    return null
+}
+
+export function formatMessageIdMarker(ref: string): string {
+    return `Message ID: ${ref}`
+}
+
+export function assignMessageRefs(state: SessionState, messages: WithParts[]): number {
+    let assigned = 0
+
+    for (const message of messages) {
+        const rawMessageId = message.info.id
+        if (typeof rawMessageId !== "string" || rawMessageId.length === 0) {
+            continue
+        }
+
+        const existingRef = state.messageIds.byRawId.get(rawMessageId)
+        if (existingRef) {
+            if (state.messageIds.byRef.get(existingRef) !== rawMessageId) {
+                state.messageIds.byRef.set(existingRef, rawMessageId)
+            }
+            continue
+        }
+
+        const ref = allocateNextMessageRef(state)
+        state.messageIds.byRawId.set(rawMessageId, ref)
+        state.messageIds.byRef.set(ref, rawMessageId)
+        assigned++
+    }
+
+    return assigned
+}
+
+function allocateNextMessageRef(state: SessionState): string {
+    let candidate = Number.isInteger(state.messageIds.nextRef)
+        ? Math.max(MESSAGE_REF_MIN_INDEX, state.messageIds.nextRef)
+        : MESSAGE_REF_MIN_INDEX
+
+    while (candidate <= MESSAGE_REF_MAX_INDEX) {
+        const ref = formatMessageRef(candidate)
+        if (!state.messageIds.byRef.has(ref)) {
+            state.messageIds.nextRef = candidate + 1
+            return ref
+        }
+        candidate++
+    }
+
+    throw new Error(
+        `Message ID alias capacity exceeded. Cannot allocate more than ${formatMessageRef(MESSAGE_REF_MAX_INDEX)} aliases in this session.`,
+    )
+}

lib/messages/index.ts

@@ -1,2 +1,3 @@
 export { prune } from "./prune"
 export { insertCompressToolContext } from "./inject/inject"
+export { insertMessageIdContext } from "./inject/inject"

lib/messages/inject/inject.ts

@@ -1,6 +1,8 @@
 import type { SessionState, WithParts } from "../../state"
 import type { Logger } from "../../logger"
 import type { PluginConfig } from "../../config"
+import { formatMessageIdMarker } from "../../message-ids"
+import { createSyntheticTextPart, createSyntheticToolPart, isIgnoredUserMessage } from "../utils"
 import {
     addAnchor,
     applyAnchoredNudge,
@@ -56,3 +58,52 @@ export const insertCompressToolContext = (
         persistAnchors(state, logger)
     }
 }
+
+export const insertMessageIdContext = (state: SessionState, messages: WithParts[]): void => {
+    const { modelId } = getModelInfo(messages)
+    const toolModelId = modelId || ""
+
+    for (const message of messages) {
+        if (message.info.role === "user" && isIgnoredUserMessage(message)) {
+            continue
+        }
+
+        const messageRef = state.messageIds.byRawId.get(message.info.id)
+        if (!messageRef) {
+            continue
+        }
+
+        const marker = formatMessageIdMarker(messageRef)
+
+        if (message.info.role === "user") {
+            const hasMarker = message.parts.some(
+                (part) => part.type === "text" && part.text.trim() === marker,
+            )
+            if (!hasMarker) {
+                message.parts.push(createSyntheticTextPart(message, marker))
+            }
+            continue
+        }
+
+        if (message.info.role !== "assistant") {
+            continue
+        }
+
+        const hasMarker = message.parts.some((part) => {
+            if (part.type !== "tool") {
+                return false
+            }
+            if (part.tool !== "context_info") {
+                return false
+            }
+            return (
+                part.state?.status === "completed" &&
+                typeof part.state.output === "string" &&
+                part.state.output.trim() === marker
+            )
+        })
+        if (!hasMarker) {
+            message.parts.push(createSyntheticToolPart(message, marker, toolModelId))
+        }
+    }
+}

lib/prompts/compress.md

@@ -41,7 +41,7 @@ Rules:
 - Include every required block placeholder exactly once.
 - Do not invent placeholders for blocks outside the selected range.
 - Treat `{block_N}` placeholders as RESERVED TOKENS. Do not emit `{block_N}` text anywhere except intentional placeholders.
-- If you need to mention a block in prose, use plain text like `compressed block #N` (without curly braces).
+- If you need to mention a block in prose, use plain text like `compressed bN` (without curly braces).
 - Preflight check before finalizing: the set of `{block_N}` placeholders in your summary must exactly match the required set, with no duplicates.
 
 These placeholders are semantic references. They will be replaced with the full stored compressed block content when the tool processes your output.
@@ -66,7 +66,7 @@ Exploration exhausted and patterns understood
 Compress smaller ranges when:
 You need to discard dead-end noise without waiting for a whole chapter to close
 You need to preserve key findings from a narrow slice while freeing context quickly
-You can bound a stale range cleanly with unique boundaries
+You can bound a stale range cleanly with injected IDs
 
 Do NOT compress when:
 You may need exact code, error messages, or file contents from the range in the immediate next steps
@@ -75,40 +75,28 @@ You cannot identify reliable boundaries yet
 
 Before compressing, ask: _"Is this range closed enough to become summary-only right now?"_ Compression is irreversible. The summary replaces everything in the range.
 
-BOUNDARY MATCHING
-You specify boundaries by matching unique text strings in the conversation. CRITICAL: In code-centric conversations, strings repeat often. Provide sufficiently unique text to match exactly once. Be conservative and choose longer, highly specific boundaries when in doubt. If a match fails (not found or found multiple times), the tool will error - extend your boundary string with more surrounding context in order to make SURE the tool does NOT error.
+BOUNDARY IDS
+You specify boundaries by ID
 
-WHERE TO PICK STRINGS FROM (important for reliable matching):
+Use the injected IDs visible in the conversation:
 
-- Your own assistant text responses (MOST RELIABLE - always stored verbatim)
-- The user's own words in their messages
-- Tool result output text (distinctive substrings within the output)
-- Previous compress summaries
-- Tool input string values (LEAST RELIABLE - only single concrete field values, not keys or schema fields, may be transformed by AI SDK)
+- `mNNNN` IDs identify raw messages
+- `bN` IDs identify previously compressed blocks
 
-NEVER USE GENERIC OR REPEATING STRINGS:
-
-Tool status messages repeat identically across every invocation. These are ALWAYS ambiguous:
-
-- "Edit applied successfully." (appears in EVERY successful edit)
-- "File written successfully" or any tool success/error boilerplate
-- Common tool output patterns that are identical across calls
-
-Instead, combine the generic output with surrounding unique context (a file path, a specific code snippet, or your own unique assistant text).
+Rules:
 
-Each boundary string you choose MUST be unique to ONE specific message. Before using a string, ask: "Could this exact text appear in any other place in this conversation?" If yes, extend it or pick a different string.
+- Pick `startId` and `endId` directly from injected IDs in context.
+- IDs must exist in the current visible context.
+- `startId` must appear before `endId`.
+- Prefer boundaries that produce short, closed ranges.
 
-WHERE TO NEVER PICK STRINGS FROM:
+ID SOURCES
 
-- `<system-reminder>` tags or any XML wrapper/meta-commentary around messages
-- Injected system instructions (plan mode text, max-steps warnings, mode-switch text, environment info)
-- Reasoning parts or chain-of-thought text
-- File/directory listing framing text (e.g. "Called the Read tool with the following input...")
-- Strings that span across message or part boundaries
-- Entire serialized JSON objects (key ordering may differ - pick a distinctive substring within instead)
+- User messages include a text marker with their `mNNNN` ID.
+- Assistant messages include a `context_info` tool marker with their `mNNNN` ID.
+- Compressed blocks are addressable by `bN` IDs.
 
-CRITICAL: AVOID USING TOOL INPUT VALUES
-NEVER use tool input schema keys or field names as boundary strings (e.g., "startString", "endString", "filePath", "content"). These may be transformed by the AI SDK and are not reliable. The ONLY acceptable use of tool input strings is a SINGLE concrete field VALUE (not the key), and even then, prefer using assistant text, user messages, or tool result outputs instead. When in doubt, choose boundaries from your own assistant responses or distinctive user message content.
+Do not invent IDs. Use only IDs that are present in context.
 
 PARALLEL COMPRESS EXECUTION
 When multiple independent ranges are ready and their boundaries do not overlap, launch MULTIPLE `compress` calls in parallel in a single response. This is the PREFERRED pattern over a single large-range compression when the work can be safely split. Run compression sequentially only when ranges overlap or when a later range depends on the result of an earlier compression.
@@ -119,8 +107,8 @@ THE FORMAT OF COMPRESS
 {
   topic: string,           // Short label (3-5 words) - e.g., "Auth System Exploration"
   content: {
-    startString: string,   // Unique text string marking the beginning of the range
-    endString: string,     // Unique text string marking the end of the range
+    startId: string,       // Boundary ID at range start: mNNNN or bN
+    endId: string,         // Boundary ID at range end: mNNNN or bN
     summary: string        // Complete technical summary replacing all content in the range
   }
 }

lib/prompts/nudge.md

@@ -31,10 +31,7 @@ Do not jump to a single broad range when the same cleanup can be done safely wit
 
 If you are performing a critical atomic operation, do not interrupt it, but make sure to perform context management rapidly
 
-BE VERY MINDFUL of the startString and endString you use for compression for RELIABLE boundary matching. NEVER use generic tool outputs like "Edit applied successfully." or generic status message as boundaries. Use unique assistant text or distinctive content instead with enough surrounding context to ensure uniqueness.
-
-CRITICAL: AVOID USING TOOL INPUT VALUES AS BOUNDARIES
-NEVER use tool input schema keys or field names. The ONLY acceptable use of tool input strings is a SINGLE concrete field VALUE (not the key), and even then, prefer assistant text, user messages, or tool result outputs instead.
+Use injected boundary IDs for compression (`mNNNN` for messages, `bN` for compressed blocks). Pick IDs that are visible in context and ensure `startId` appears before `endId`.
 
 Ensure your summaries are inclusive of all parts of the range.
 If the compressed range includes user messages, preserve user intent exactly. Prefer direct quotes for short user messages to avoid semantic drift.

lib/state/state.ts

@@ -76,6 +76,11 @@ export function createSessionState(): SessionState {
         },
         toolParameters: new Map<string, ToolParameterEntry>(),
         toolIdList: [],
+        messageIds: {
+            byRawId: new Map<string, string>(),
+            byRef: new Map<string, string>(),
+            nextRef: 0,
+        },
         lastCompaction: 0,
         currentTurn: 0,
         variant: undefined,
@@ -101,6 +106,11 @@ export function resetSessionState(state: SessionState): void {
     }
     state.toolParameters.clear()
     state.toolIdList = []
+    state.messageIds = {
+        byRawId: new Map<string, string>(),
+        byRef: new Map<string, string>(),
+        nextRef: 0,
+    }
     state.lastCompaction = 0
     state.currentTurn = 0
     state.variant = undefined

lib/state/types.ts

@@ -37,6 +37,12 @@ export interface PendingManualTrigger {
     prompt: string
 }
 
+export interface MessageIdState {
+    byRawId: Map<string, string>
+    byRef: Map<string, string>
+    nextRef: number
+}
+
 export interface SessionState {
     sessionId: string | null
     isSubAgent: boolean
@@ -48,6 +54,7 @@ export interface SessionState {
     stats: SessionStats
     toolParameters: Map<string, ToolParameterEntry>
     toolIdList: string[]
+    messageIds: MessageIdState
     lastCompaction: number
     currentTurn: number
     variant: string | undefined