RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Fix: An additional retrieval node has appeared in the agent created using the CAJAL Scientific Paper Assistant template. (#21079)
balibabufb015ecfb712
diff --git a/internal/agent/templates/cajal_scientific_paper_agent.json b/internal/agent/templates/cajal_scientific_paper_agent.jsonindex 235c4a8b82..c5cb3a77a8 100644--- a/internal/agent/templates/cajal_scientific_paper_agent.json+++ b/internal/agent/templates/cajal_scientific_paper_agent.json@@ -157,6 +157,13 @@"targetHandle": "end","type": "buttonEdge","zIndex": 1001+ },+ {+ "id": "xy-edge__Agent:NewPumasLicktool-Tool:QuietPapersCiteend",+ "source": "Agent:NewPumasLick",+ "sourceHandle": "tool",+ "target": "Tool:QuietPapersCite",+ "targetHandle": "end"}],"nodes": [@@ -295,6 +302,30 @@"sourcePosition": "right","targetPosition": "left","type": "agentNode"+ },+ {+ "data": {+ "form": {+ "description": "This is an agent for a specific task.",+ "user_prompt": "This is the order you need to send to the agent."+ },+ "label": "Tool",+ "name": "flow.tool_0"+ },+ "dragging": false,+ "id": "Tool:QuietPapersCite",+ "measured": {+ "height": 48,+ "width": 200+ },+ "position": {+ "x": 265.00048227952215,+ "y": 326.49109364794631+ },+ "selected": false,+ "sourcePosition": "right",+ "targetPosition": "left",+ "type": "toolNode"}]},diff --git a/web/src/components/next-markdown-content/__tests__/index.test.tsx b/web/src/components/next-markdown-content/__tests__/index.test.tsxnew file mode 100644index 0000000000..ed2f21356f--- /dev/null+++ b/web/src/components/next-markdown-content/__tests__/index.test.tsx@@ -0,0 +1,213 @@+import { render, screen } from '@testing-library/react';++import MarkdownContent from '..';++jest.mock('react-i18next', () => ({+ useTranslation: () => ({ t: (key: string) => key }),+}));++jest.mock('@/hooks/use-document-request', () => ({+ useFetchDocumentThumbnailsByIds: () => ({+ setDocumentIds: jest.fn(),+ data: {},+ }),+}));++jest.mock('@/hooks/use-loading-pause', () => ({+ useLoadingPause: () => false,+}));++// Only the artifact download handlers use these; mocking them keeps the+// file-util → service → i18n-config import chain out of the suite.+jest.mock('@/utils/file-util', () => ({+ downloadFileFromBlob: jest.fn(),+}));++jest.mock('@/utils/request', () => ({+ __esModule: true,+ default: jest.fn(),+}));++// Render the highlighter as a plain <pre>: the assertions target citation+// resolution, not code highlighting.+jest.mock('react-syntax-highlighter', () => ({+ __esModule: true,+ default: ({ children }: any) => {+ const ReactLib = jest.requireActual('react');+ return ReactLib.createElement('pre', null, children);+ },+}));++// react-markdown and the remark/rehype packages are ESM-only and jest does+// not transform node_modules, so the real parser cannot run here. The+// production pipeline wraps every text node in <custom-typography>; this+// mock feeds the full content string through that same component, which is+// where citation markers are replaced.+jest.mock('react-markdown', () => ({+ __esModule: true,+ default: ({ children, components }: any) => {+ const ReactLib = jest.requireActual('react');+ const CustomTypography = components['custom-typography'];+ return ReactLib.createElement(CustomTypography, null, String(children));+ },+}));++jest.mock('rehype-katex', () => jest.fn());+jest.mock('rehype-raw', () => jest.fn());+jest.mock('unist-util-visit-parents', () => ({ visitParents: jest.fn() }));+jest.mock('@/constants/markdown-remark-plugins', () => ({+ MarkdownRemarkPlugins: [],+ MarkdownRemarkPluginsLite: [],+}));+jest.mock('@/constants/markdown-rehype-plugins', () => ({+ RehypeSanitizeAssistantMarkdown: jest.fn(),+}));++// Radix HoverCard only mounts its content on hover; render eagerly so the+// resolved chunk content is assertable in the DOM.+jest.mock('@/components/ui/hover-card', () => ({+ HoverCard: ({ children }: any) => {+ const ReactLib = jest.requireActual('react');+ return ReactLib.createElement(+ 'div',+ { 'data-testid': 'citation' },+ children,+ );+ },+ HoverCardTrigger: ({ children }: any) => {+ const ReactLib = jest.requireActual('react');+ return ReactLib.createElement('span', { 'data-testid': 'chip' }, children);+ },+ HoverCardContent: ({ children }: any) => {+ const ReactLib = jest.requireActual('react');+ return ReactLib.createElement(+ 'div',+ { 'data-testid': 'popover' },+ children,+ );+ },+}));++jest.mock('@/components/svg-icon', () => ({+ __esModule: true,+ default: () => {+ const ReactLib = jest.requireActual('react');+ return ReactLib.createElement('span');+ },+}));++jest.mock('@/components/image', () => ({+ __esModule: true,+ default: () => null,+ AuthenticatedImg: () => null,+}));++const buildChunk = (id: string, content: string, documentId: string) => ({+ id,+ chunk_id: id,+ content,+ content_with_weight: content,+ document_id: documentId,+ doc_id: documentId,+ image_id: '',+ img_id: '',+});++const HappyPrince = buildChunk(+ 'a2d067519c9e0db1',+ 'HAPPY_PRINCE_CHUNK_CONTENT',+ 'doc-happy-prince',+);+const Nightingale = buildChunk(+ 'b3e178620da1fc42',+ 'NIGHTINGALE_CHUNK_CONTENT',+ 'doc-nightingale',+);++// reference.chunks ships in retrieval order — Happy Prince ranked first —+// while the answer cites Nightingale first. The array shape is what the Go+// agent run actually sends on the wire.+const buildReference = () =>+ ({+ chunks: [HappyPrince, Nightingale],+ doc_aggs: {+ 'doc-happy-prince': {+ doc_id: 'doc-happy-prince',+ doc_name: 'The Happy Prince.txt',+ count: 1,+ },+ 'doc-nightingale': {+ doc_id: 'doc-nightingale',+ doc_name: 'The Nightingale and the Rose.txt',+ count: 1,+ },+ },+ total: 2,+ }) as any;++const chipTexts = () =>+ screen.getAllByTestId('chip').map((chip) => chip.textContent);+const popoverTexts = () =>+ screen.getAllByTestId('popover').map((popover) => popover.textContent);++describe('MarkdownContent citations', () => {+ it('resolves agent [ID:<chunkId>] markers by chunk id, not citation order', () => {+ render(+ <MarkdownContent+ content={+ 'The same volume includes The Nightingale and the Rose [ID:b3e178620da1fc42] and the tears of the prince [ID:a2d067519c9e0db1].'+ }+ loading={false}+ reference={buildReference()}+ />,+ );++ expect(chipTexts()).toEqual(['[1]', '[2]']);+ const popovers = popoverTexts();+ expect(popovers[0]).toContain('NIGHTINGALE_CHUNK_CONTENT');+ expect(popovers[0]).toContain('The Nightingale and the Rose.txt');+ expect(popovers[1]).toContain('HAPPY_PRINCE_CHUNK_CONTENT');+ expect(popovers[1]).toContain('The Happy Prince.txt');+ });++ it('resolves numeric markers by the index they carry, not citation order', () => {+ render(+ <MarkdownContent+ content={'Cites the second chunk first [ID:1] then the first [ID:0].'}+ loading={false}+ reference={buildReference()}+ />,+ );++ expect(chipTexts()).toEqual(['[1]', '[2]']);+ const popovers = popoverTexts();+ expect(popovers[0]).toContain('NIGHTINGALE_CHUNK_CONTENT');+ expect(popovers[1]).toContain('HAPPY_PRINCE_CHUNK_CONTENT');+ });++ it('keeps an unresolvable marker as literal text once loading finished', () => {+ const { container } = render(+ <MarkdownContent+ content={'A hallucinated source [ID:ffffffffffffffff] stays text.'}+ loading={false}+ reference={buildReference()}+ />,+ );++ expect(screen.queryByTestId('chip')).toBeNull();+ expect(container.textContent).toContain('[ID:ffffffffffffffff]');+ });++ it('renders the chip without popover while the reference is still streaming', () => {+ render(+ <MarkdownContent+ content={'Sources arriving [ID:b3e178620da1fc42] soon.'}+ loading={true}+ reference={undefined}+ />,+ );++ expect(chipTexts()).toEqual(['[1]']);+ expect(screen.queryByTestId('popover')).toBeNull();+ });+});diff --git a/web/src/components/next-markdown-content/index.tsx b/web/src/components/next-markdown-content/index.tsxindex 23a43ffae1..827db3ab92 100644--- a/web/src/components/next-markdown-content/index.tsx+++ b/web/src/components/next-markdown-content/index.tsx@@ -49,8 +49,10 @@ import {replaceRetrievingToSection,replaceTextByOldReg,replaceThinkToSection,+ resolveCitationChunk,unescapeAngleBrackets,} from '@/utils/chat';+import type { CitationKey } from '@/utils/citation-utils';import { getDirAttribute } from '@/utils/text-direction';import { useFetchDocumentThumbnailsByIds } from '@/hooks/use-document-request';@@ -72,6 +74,11 @@ import styles from './index.module.less';const getChunkKey = (match: string) => parseCitationIndex(match);+// react-string-replace hands the callback the LAST capture group, not the+// full match — citationMarkerReg groups only the id, so replacing with it+// would strip the brackets. This group wraps the whole marker, letting an+// unresolved marker be returned unchanged.+const WholeMarkerReg = /(\[(?:ID:)?[0-9a-fA-F\u0660-\u0669\u06F0-\u06F9]+\])/g;const isArtifactUrl = (url?: string) =>Boolean(url && url.includes('/api/v1/documents/artifact/'));@@ -278,12 +285,10 @@ function MarkdownContent({};const getReferenceInfo = useCallback(- (chunkIndex: number) => {- const chunks = reference?.chunks ?? {};- // Agent reference.chunks is a Record keyed by the original citation ID- // (e.g. "3092e7ae6831b877"); the caller maps those IDs to a positional- // display index, so look up the N-th entry by insertion order.- const chunkItem = Object.values(chunks)[chunkIndex];+ (chunkKey: CitationKey) => {+ // The marker itself selects the chunk: a numeric key indexes the+ // payload, an agent [ID:<chunkId>] key matches the chunk's own id.+ const chunkItem = resolveCitationChunk(reference?.chunks, chunkKey);const documentList = Object.values(reference?.doc_aggs ?? {});const document = documentList.find(@@ -309,7 +314,7 @@ function MarkdownContent({);const renderPopoverContent = useCallback(- (chunkIndex: number) => {+ (chunkKey: CitationKey) => {const {documentUrl,fileThumbnail,@@ -318,10 +323,16 @@ function MarkdownContent({chunkItem,documentId,document,- } = getReferenceInfo(chunkIndex);+ } = getReferenceInfo(chunkKey);++ // The citation chip already gates on the chunk being found; this narrows+ // chunkItem for the handlers below.+ if (!chunkItem) {+ return null;+ }return (- <div key={chunkItem?.id} className="flex gap-2">+ <div key={chunkItem.id} className="flex gap-2">{imageId && (<HoverCard><HoverCardTrigger>@@ -385,14 +396,24 @@ function MarkdownContent({const renderReference = useCallback((text: string) => {- // Assign each unique citation marker a stable display number based on- // its first occurrence, so the same ID always renders as the same [N]- // chip. The actual chunk lookup uses that index against the positional- // order of IReferenceObject.chunks (see getReferenceInfo).+ // Chip numbers follow each unique marker's first occurrence, so the+ // same citation always renders as the same [N] chip. That numbering is+ // display-only: the chunk behind a marker is resolved from the marker+ // itself (position for numeric markers, chunk id for agent+ // [ID:<chunkId>] markers), never from the display position — the+ // payload ships in retrieval order, which is unrelated to the order+ // the answer cites passages in.const keyToDisplay = buildCitationDisplayMap(text);- const replacedText = reactStringReplace(text, currentReg, (match) => {+ const replacedText = reactStringReplace(text, WholeMarkerReg, (match) => {const chunkKey = getChunkKey(match);const displayIndex = keyToDisplay.get(chunkKey) ?? 0;+ const chunkItem = resolveCitationChunk(reference?.chunks, chunkKey);+ // The reference lands at message_end, after the answer stream, so an+ // unresolved marker keeps its chip while loading. Afterwards it+ // stays as literal text rather than pointing at the wrong chunk.+ if (!chunkItem && !loading) {+ return match;+ }return (<HoverCard key={`${String(chunkKey)}-${displayIndex}`}>@@ -401,16 +422,18 @@ function MarkdownContent({[{displayIndex + 1}]</bdi></HoverCardTrigger>- <HoverCardContent className="max-w-3xl">- {renderPopoverContent(displayIndex)}- </HoverCardContent>+ {chunkItem && (+ <HoverCardContent className="max-w-3xl">+ {renderPopoverContent(chunkKey)}+ </HoverCardContent>+ )}</HoverCard>);});return replacedText;},- [renderPopoverContent],+ [loading, reference?.chunks, renderPopoverContent],);const dir = getDirAttribute(content?.replace(currentReg, ''));diff --git a/web/src/components/next-message-item/reference-image-list.tsx b/web/src/components/next-message-item/reference-image-list.tsxindex b9a6c45449..9aacd9c1d3 100644--- a/web/src/components/next-message-item/reference-image-list.tsx+++ b/web/src/components/next-message-item/reference-image-list.tsx@@ -26,9 +26,8 @@ import {import { useSetModalState } from '@/hooks/common-hooks';import { IReferenceChunk } from '@/interfaces/database/chat';import PdfDrawer from '@/pages/next-search/document-preview-modal';-import { buildCitationDisplayMap } from '@/utils/chat';+import { buildCitationDisplayMap, resolveCitationChunk } from '@/utils/chat';import { middleEllipsis } from '@/utils/common-util';-import { isPlainObject } from 'lodash';import { RotateCw, ZoomIn, ZoomOut } from 'lucide-react';import { useMemo } from 'react';import { PhotoProvider, PhotoView } from 'react-photo-view';@@ -182,28 +181,15 @@ export function ReferenceImageList({messageContent,}: IProps) {const images = useMemo(() => {- // In plain chat the body chips (markdown-content) treat a numeric marker- // [n] as the 0-based index into the full retrieved chunks array and render- // [n + 1], so the carousel must index chunks by that same key and label- // it n + 1 — indexing by first-occurrence position would show unrelated- // chunks whenever retrieval returns more chunks than the model cited.- // Agent markers are [ID:<chunkId>] strings; those keep the positional- // ordering (matched by chunk.id first, when possible).+ // The marker itself selects the chunk: plain-chat numeric markers index+ // the retrieved chunks array (chip renders n + 1); agent [ID:<chunkId>]+ // markers match the chunk's own id. Either way a citation lands on its+ // own chunk regardless of the payload's retrieval order.const keyToPosition = buildCitationDisplayMap(messageContent);- const chunkList = Array.isArray(referenceChunks)- ? referenceChunks- : isPlainObject(referenceChunks)- ? Object.values(referenceChunks ?? {})- : [];return [...keyToPosition.entries()].map(([key, position]) => {- const chunk =- typeof key === 'number'- ? chunkList[key]- : ((Array.isArray(referenceChunks)- ? referenceChunks.find((item) => item.id === String(key))- : referenceChunks?.[String(key)]) ?? chunkList[position]);+ const chunk = resolveCitationChunk(referenceChunks, key);if (!chunk?.image_id || !chunk?.document_id) {return null;}diff --git a/web/src/pages/agent/hooks/use-add-node.test.tsx b/web/src/pages/agent/hooks/use-add-node.test.tsxindex a115c3e577..ac36b264c3 100644--- a/web/src/pages/agent/hooks/use-add-node.test.tsx+++ b/web/src/pages/agent/hooks/use-add-node.test.tsx@@ -139,6 +139,43 @@ describe('useAddNode', () => {});});+ it('adds a tool node only once when the same stale callback fires twice', () => {+ // Mirrors the React StrictMode double-invoked mount effect in+ // ToolPopover: both invocations share one render's closure, so the+ // second call must consult fresh store state to see the edge the+ // first call just committed. Otherwise two tool nodes stack at the+ // same position below the agent.+ const agentNode = {+ id: 'Agent:0',+ type: 'agentNode',+ position: { x: 100, y: 100 },+ data: {+ label: Operator.Agent,+ name: 'agent_0',+ form: { tools: [{ component_name: Operator.Retrieval }] },+ },+ };+ useGraphStore.setState({ nodes: [agentNode], edges: [] });++ const { result } = renderHook(() => useAddNode());++ const addTool = result.current.addCanvasNode(Operator.Tool, {+ nodeId: 'Agent:0',+ position: Position.Bottom,+ });++ act(() => {+ addTool();+ addTool();+ });++ const { nodes, edges } = useGraphStore.getState();+ expect(nodes.filter((x) => x.data.label === Operator.Tool)).toHaveLength(1);+ expect(+ edges.filter((x) => x.sourceHandle === NodeHandleId.Tool),+ ).toHaveLength(1);+ });+it('adds an iteration node again after the previous one was deleted', () => {useGraphStore.setState({ nodes: [createSwitchNode()], edges: [] });diff --git a/web/src/pages/agent/hooks/use-add-node.ts b/web/src/pages/agent/hooks/use-add-node.tsindex 27804925d8..16044ca2fd 100644--- a/web/src/pages/agent/hooks/use-add-node.ts+++ b/web/src/pages/agent/hooks/use-add-node.ts@@ -337,15 +337,20 @@ function useAddChildEdge() {}function useAddToolNode() {- const { nodes, edges, addEdge, getNode, addNode } = useGraphStore(- (state) => state,- );+ const { addEdge, getNode, addNode } = useGraphStore((state) => state);const addToolNode = useCallback((newNode: Node<any>, nodeId?: string): boolean => {const agentNode = getNode(nodeId);if (agentNode) {+ // Read edges/nodes from the store at call time, not from the+ // render-time snapshot: React StrictMode double-invokes the mount+ // effect that auto-adds this node (ToolPopover), and the second+ // invocation must see the edge the first one just committed —+ // otherwise both pass the guard and stack a duplicate tool node at+ // the same position.+ const { nodes, edges } = useGraphStore.getState();const childToolNodeIds = edges.filter((x) => x.source === nodeId && x.sourceHandle === NodeHandleId.Tool,@@ -377,7 +382,7 @@ function useAddToolNode() {}return false;},- [addEdge, addNode, edges, getNode, nodes],+ [addEdge, addNode, getNode],);return { addToolNode };diff --git a/web/src/utils/__tests__/citation-utils.test.ts b/web/src/utils/__tests__/citation-utils.test.tsnew file mode 100644index 0000000000..99bb9737ec--- /dev/null+++ b/web/src/utils/__tests__/citation-utils.test.ts@@ -0,0 +1,91 @@+import type { IReferenceChunk } from '@/interfaces/database/chat';+import {+ buildCitationDisplayMap,+ parseCitationIndex,+ resolveCitationChunk,+} from '../citation-utils';++const buildChunk = (id: string): IReferenceChunk => ({+ id,+ content: null,+ document_id: `doc-${id}`,+ document_name: `${id}.txt`,+ dataset_id: 'kb-1',+ image_id: '',+ similarity: 1,+ vector_similarity: 1,+ term_similarity: 1,+ positions: [],+});++const HappyPrince = buildChunk('a2d067519c9e0db1');+const Nightingale = buildChunk('b3e178620da1fc42');++describe('parseCitationIndex', () => {+ it('parses numeric markers as numbers', () => {+ expect(parseCitationIndex('[ID:2]')).toBe(2);+ expect(parseCitationIndex('[3]')).toBe(3);+ });++ it('parses hex chunk-id markers as strings', () => {+ expect(parseCitationIndex('[ID:a2d067519c9e0db1]')).toBe(+ 'a2d067519c9e0db1',+ );+ });+});++describe('resolveCitationChunk', () => {+ // The payload ships in retrieval order: Happy Prince ranked first.+ const chunks = [HappyPrince, Nightingale];++ it('resolves a numeric key positionally', () => {+ expect(resolveCitationChunk(chunks, 0)).toBe(HappyPrince);+ expect(resolveCitationChunk(chunks, 1)).toBe(Nightingale);+ });++ it('returns undefined for an out-of-range numeric key', () => {+ expect(resolveCitationChunk(chunks, 5)).toBeUndefined();+ });++ it('resolves a chunk-id key by id, not by citation order', () => {+ // The answer cites Nightingale first; the chunk must still be the one+ // the marker names, not chunks[0] (the mis-citation regression).+ expect(resolveCitationChunk(chunks, 'b3e178620da1fc42')).toBe(Nightingale);+ expect(resolveCitationChunk(chunks, 'a2d067519c9e0db1')).toBe(HappyPrince);+ });++ it('falls back to chunk_id when the id field is absent', () => {+ const legacy = [+ { chunk_id: 'b3e178620da1fc42' } as unknown as IReferenceChunk,+ ];+ expect(resolveCitationChunk(legacy, 'b3e178620da1fc42')).toBe(legacy[0]);+ });++ it('returns undefined for an unknown chunk id instead of guessing positionally', () => {+ expect(resolveCitationChunk(chunks, 'ffffffffffffffff')).toBeUndefined();+ });++ it('resolves ids inside a Record-shaped payload', () => {+ const record = {+ a2d067519c9e0db1: HappyPrince,+ b3e178620da1fc42: Nightingale,+ };+ expect(resolveCitationChunk(record, 'b3e178620da1fc42')).toBe(Nightingale);+ });++ it('tolerates an empty payload', () => {+ expect(resolveCitationChunk(undefined, 0)).toBeUndefined();+ expect(resolveCitationChunk(null, 'a2d067519c9e0db1')).toBeUndefined();+ });+});++describe('buildCitationDisplayMap', () => {+ it('numbers unique markers by first occurrence, whatever their key', () => {+ const map = buildCitationDisplayMap(+ 'nightingale [ID:b3e178620da1fc42] then happy prince [ID:a2d067519c9e0db1] again [ID:b3e178620da1fc42]',+ );+ expect(map.get('b3e178620da1fc42')).toBe(0);+ expect(map.get('a2d067519c9e0db1')).toBe(1);+ expect(map.size).toBe(2);+ });+});diff --git a/web/src/utils/chat.ts b/web/src/utils/chat.tsindex ccf0dbbcb9..095cd8a8f5 100644--- a/web/src/utils/chat.ts+++ b/web/src/utils/chat.ts@@ -27,6 +27,7 @@ import {citationMarkerReg,normalizeCitationDigits,parseCitationIndex,+ resolveCitationChunk,} from './citation-utils';export const isConversationIdExist = (conversationId: string) => {@@ -256,7 +257,13 @@ export function setChatVariableEnabledFieldValuePage() {const oldReg = /(#{2}[0-9\u0660-\u0669\u06F0-\u06F9]+\${2})/g;export const currentReg = citationMarkerReg;-export { buildCitationDisplayMap, normalizeCitationDigits, parseCitationIndex };+export {+ buildCitationDisplayMap,+ normalizeCitationDigits,+ parseCitationIndex,+ resolveCitationChunk,+};+export type { CitationKey } from './citation-utils';// To be compatible with the old index matching modeexport const replaceTextByOldReg = (text: string) => {diff --git a/web/src/utils/citation-utils.ts b/web/src/utils/citation-utils.tsindex 4387834654..10e0af20c4 100644--- a/web/src/utils/citation-utils.ts+++ b/web/src/utils/citation-utils.ts@@ -14,6 +14,8 @@* limitations under the License.*/+import type { IReferenceChunk } from '@/interfaces/database/chat';+export const normalizeCitationDigits = (text: string) => {if (!text) return text;return text.replace(/[٠-٩۰-۹]/g, (char) => {@@ -46,10 +48,38 @@ export const parseCitationIndex = (value: string): CitationKey => {export const citationMarkerReg =/\[(?:ID:)?([0-9a-fA-F\u0660-\u0669\u06F0-\u06F9]+)\]/g;+// Resolve the chunk a citation marker points at. A numeric key is the+// chunk's position in the payload — the plain-chat contract, where the+// backend numbers each marker by its index into reference.chunks. A string+// key is the chunk id an agent answer embeds in its [ID:<chunkId>] markers;+// match it against the chunk's own id, never positionally: the payload+// ships in retrieval order, which is unrelated to the order the answer+// cites passages in, so a positional read permutes the sources. A chunk id+// is 16 hex chars — an all-digit id would parse as a position (~0.05% per+// id), accepted and recorded here so it is not rediscovered as a mystery.+export const resolveCitationChunk = (+ chunks:+ | IReferenceChunk[]+ | Record<string, IReferenceChunk>+ | null+ | undefined,+ key: CitationKey,+): IReferenceChunk | undefined => {+ const list = Array.isArray(chunks) ? chunks : Object.values(chunks ?? {});+ if (typeof key === 'number') {+ return list[key];+ }+ return list.find(+ (chunk) =>+ chunk?.id === key ||+ (chunk as { chunk_id?: string } | undefined)?.chunk_id === key,+ );+};+// Map each unique citation marker ([n] or [ID:<chunkId>]) to its stable-// 0-based display position by first occurrence. The chip renders position + 1-// and the chunk is looked up positionally via Object.values(chunks)[position].-// Works for both plain chat (numeric markers) and agents ([ID:<chunkId>]).+// 0-based display position by first occurrence; the chip renders+// position + 1. This numbering is display-only — the chunk behind a marker+// is resolved by resolveCitationChunk, never by this position.export const buildCitationDisplayMap = (content: string,): Map<CitationKey, number> => {