implement anchor query parsing and matching logic

Author: spoons-and-mirrors

lib/tools/utils.ts

@@ -19,6 +19,12 @@ interface MatchResult {
     matchType: "exact" | "fuzzy"
 }
 
+interface AnchorQuery {
+    type: "muid" | "uid"
+    value: string
+    id: string
+}
+
 function summarizeMatches(
     matches: MatchResult[],
     limit = 8,
@@ -94,6 +100,91 @@ function extractMessageContent(msg: WithParts): string {
     return content
 }
 
+function parseAnchorQuery(searchString: string): AnchorQuery | undefined {
+    const muid = searchString.match(/^\[(muid)_(\d+)\]$/)
+    if (muid) {
+        return {
+            type: "muid",
+            value: searchString,
+            id: muid[2],
+        }
+    }
+
+    const uid = searchString.match(/^\[(uid)_(\d+)\]$/)
+    if (uid) {
+        return {
+            type: "uid",
+            value: searchString,
+            id: uid[2],
+        }
+    }
+
+    return undefined
+}
+
+function findAnchorMatches(messages: WithParts[], anchor: AnchorQuery): MatchResult[] {
+    if (anchor.type === "muid") {
+        const matches: MatchResult[] = []
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i]
+            if (msg.info.role !== "user") {
+                continue
+            }
+            const parts = Array.isArray(msg.parts) ? msg.parts : []
+            const found = parts.some(
+                (part) =>
+                    part.type === "text" &&
+                    typeof part.text === "string" &&
+                    part.text.startsWith(anchor.value),
+            )
+            if (!found) {
+                continue
+            }
+            matches.push({
+                messageId: msg.info.id,
+                messageIndex: i,
+                score: 100,
+                matchType: "exact",
+            })
+        }
+        return matches
+    }
+
+    const matches: MatchResult[] = []
+    const uidPrefix = new RegExp(`^\\[uid_${anchor.id}(?:\\]|,)`)
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i]
+        const parts = Array.isArray(msg.parts) ? msg.parts : []
+        const found = parts.some((part) => {
+            if (part.type !== "tool") {
+                return false
+            }
+
+            const output = part.state?.status === "completed" ? part.state.output : undefined
+            if (typeof output === "string" && uidPrefix.test(output)) {
+                return true
+            }
+
+            const error = part.state?.status === "error" ? part.state.error : undefined
+            if (typeof error === "string" && uidPrefix.test(error)) {
+                return true
+            }
+
+            return false
+        })
+        if (!found) {
+            continue
+        }
+        matches.push({
+            messageId: msg.info.id,
+            messageIndex: i,
+            score: 100,
+            matchType: "exact",
+        })
+    }
+    return matches
+}
+
 function findExactMatches(messages: WithParts[], searchString: string): MatchResult[] {
     const matches: MatchResult[] = []
 
@@ -152,6 +243,52 @@ export function findStringInMessages(
 
     const searchableMessages = messages.length > 1 ? messages.slice(0, -1) : messages
     const lastMessage = messages.length > 0 ? messages[messages.length - 1] : undefined
+    const anchor = parseAnchorQuery(searchString)
+
+    if (anchor) {
+        const anchorMatches = findAnchorMatches(searchableMessages, anchor)
+        const anchorSummary = summarizeMatches(anchorMatches)
+        clog.info(C.BOUNDARY, `${stringType}: anchor match results`, {
+            type: anchor.type,
+            count: anchorSummary.total,
+            sample: anchorSummary.sample,
+            omitted: anchorSummary.omitted,
+        })
+
+        if (anchorMatches.length === 1) {
+            clog.info(C.BOUNDARY, `${stringType}: single anchor match found`, {
+                messageId: anchorMatches[0].messageId,
+                messageIndex: anchorMatches[0].messageIndex,
+            })
+            return {
+                messageId: anchorMatches[0].messageId,
+                messageIndex: anchorMatches[0].messageIndex,
+            }
+        }
+
+        if (anchorMatches.length > 1) {
+            clog.error(C.BOUNDARY, `${stringType}: MULTIPLE anchor matches - ambiguous`, {
+                type: anchor.type,
+                count: anchorMatches.length,
+                matches: anchorMatches.map((m) => ({ msgId: m.messageId, idx: m.messageIndex })),
+                searchString: searchString.substring(0, 150),
+            })
+            throw new Error(
+                `Found multiple matches for ${stringType}. ` +
+                    `Use a different [muid_x] or [uid_x] anchor that appears only once.`,
+            )
+        }
+
+        clog.error(C.BOUNDARY, `${stringType}: anchor NOT FOUND`, {
+            type: anchor.type,
+            searchString: searchString.substring(0, 150),
+            messageCount: searchableMessages.length,
+        })
+        throw new Error(
+            `${stringType} anchor not found in conversation. ` +
+                `Use an existing [muid_x] or [uid_x] marker from the current context.`,
+        )
+    }
 
     clog.debug(
         C.BOUNDARY,