Skip to content

fix(bookstack): prevent thinking-text flicker, remove page ID citations#102

Merged
amrit110 merged 1 commit into
mainfrom
fix/bookstack-flicker-and-citations
Jun 16, 2026
Merged

fix(bookstack): prevent thinking-text flicker, remove page ID citations#102
amrit110 merged 1 commit into
mainfrom
fix/bookstack-flicker-and-citations

Conversation

@amrit110

Copy link
Copy Markdown
Member

Problems

1. Thinking-text flicker — Intermediate reasoning text generated by the model before a tool call was streamed to the UI, then wiped by text_clear, causing a jarring flash that users couldn't read before it disappeared.

2. Page ID citations — Custom on-prem models cited pages as "From 'X' (page 61):" using the internal numeric page ID, which is meaningless to users. The model was picking up "id": 61 from the get_page tool response and treating it as a page number. The model was also generating preamble text ("Now I have all the information…") before the answer despite the existing prompt instruction.

Fixes

bookstack_agent/ui/app/components/chat-page.tsx — RAF-based text buffering

text_chunk events are now accumulated in a ref and flushed to React state once per animation frame (requestAnimationFrame). If text_clear arrives before the RAF fires (which happens when thinking-text and the subsequent tool-use event arrive in the same TCP packet / event-loop tick), the buffer is discarded silently — no DOM update, no flicker. Once the gate opens (first RAF fires without a text_clear), subsequent chunks stream in normally per frame.

src/aieng_bot/bookstack/tools.py — strip IDs from get_page response

Removed id, book_id, chapter_id, and updated_at from the get_page tool output. The model now only sees name, markdown, and url — exactly what it needs to answer and cite. With no numeric ID visible, it can't accidentally use one as a "page number."

src/aieng_bot/bookstack/prompts.py — stronger citation and no-preamble rules

  • Added explicit ban on preamble phrases ("Now I have all the information…", "Let me synthesize…", etc.)
  • Hardened the ## Sources instruction: "NEVER include page numbers, numeric IDs, or any internal identifiers. Use only the page title and its URL." — written to be unambiguous for models that don't follow nuanced instructions as reliably as Claude.

Test plan

  • All 48 Python tests pass (pytest tests/bookstack/)
  • Ask a multi-step question; verify tool steps appear cleanly with no text flash before them
  • Verify the final answer streams in progressively
  • Verify ## Sources lists titles + URLs with no (page N) annotations

@amrit110 amrit110 merged commit d16604e into main Jun 16, 2026
9 checks passed
@amrit110 amrit110 deleted the fix/bookstack-flicker-and-citations branch June 16, 2026 17:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant