fix(doc-api): use textRanges[0] instead of highlightRange for comment anchoring#3224
fix(doc-api): use textRanges[0] instead of highlightRange for comment anchoring#3224bjohas wants to merge 1 commit into
Conversation
… anchoring
highlightRange is snippet-relative (offset by up to SNIPPET_PADDING=30
chars from the start of the block). Telling LLMs to build target.range
from it produces silently mis-anchored comments or TARGET_NOT_FOUND
errors.
The correct field is context.textRanges[0], which is a complete
block-relative TextAddress ({kind:"text", blockId, range:{start,end}})
and can be passed straight through as the comment target.
Update the superdoc_comment tool description accordingly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 16fca2d306
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| description: | ||
| 'Manage document comment threads: create, read, update, and delete. ' + | ||
| 'To create a comment, first use superdoc_search to find the target text, then pass action "create" with the comment text and a target: {kind:"text", blockId:"<blockId>", range:{start:<N>, end:<N>}} using the blockId and highlightRange from the search result. ' + | ||
| 'To create a comment, first use superdoc_search to find the target text, then pass action "create" with the comment text and a target built from the search result: use result.items[0].context.textRanges[0] directly as the target — it is already a complete {kind:"text", blockId, range:{start,end}} block-relative address. Do NOT use result.highlightRange — it is offset relative to the snippet preview (up to 30 chars off) and will mis-anchor the comment or trigger TARGET_NOT_FOUND. ' + |
There was a problem hiding this comment.
When an agent follows this new superdoc_comment guidance after superdoc_search, result.items[0].context is undefined: I checked packages/sdk/langs/browser/src/intent-dispatch.ts, where superdoc_search dispatches to doc.query.match, and the query.match schema defines text match items with target, highlightRange, and blocks, but no context or textRanges. That makes the instructed target undefined or invalid, so comment creation fails for the exact search-then-comment workflow this description documents; point to a real query.match field such as the item’s blocks range data or otherwise expose the desired text address.
Useful? React with 👍 / 👎.
2 participants
Summary
The
superdoc_commenttool description instructs LLMs to buildtarget.rangefromresult.highlightRange. ButhighlightRangeis computed relative to the snippet preview string, not the block — it is offset by up toSNIPPET_PADDING = 30characters:Following the description literally produces silently mis-anchored comments (off by ~30 chars) or
TARGET_NOT_FOUNDerrors when the offset lands past the end of the block.The correct field is
result.items[0].context.textRanges[0]— a complete block-relativeTextAddress({kind:"text", blockId, range:{start,end}}) that can be passed directly astarget. The document-api's own integration test (overview-examples.test.ts:537) already uses this pattern.Changes
packages/document-api/src/contract/operation-definitions.ts— one-line description fix: replace thehighlightRangeinstruction withcontext.textRanges[0]and add an explicit warning not to usehighlightRange.The generated
apps/mcp/src/generated/catalog.tsandmcp-prompt.tswill pick up the corrected wording whenpnpm run generate:allis run.Test plan
pnpm run generate:all— catalog and prompt regenerate cleanly.superdoc_search→ useresult.items[0].context.textRanges[0]astargetinsuperdoc_comment action:"create"— comment anchors correctly.highlightRangestill mis-anchors (so the fix is needed and the warning is accurate).🤖 Generated with Claude Code