KOAssistant v0.17.2 Release Notes

This is a maintenance and bugfix release for v0.17.x. Release notes for v0.17.1 and v0.17.0 are below.

New Features

Always-On Caching with Dynamic Permission Gating

X-Ray and Recap results are now always cached, even when text extraction is disabled. Previously, caches were only saved when text extraction was enabled — meaning users reading well-known works (where the AI uses its training knowledge) had to re-run expensive actions every time.

• Always cached: Results saved regardless of text extraction state
• Dynamic permissions: Each cache tracks whether it was built from extracted text or AI training data. Caches built without text extraction don't require text extraction permission to read
• Sticky-true: Once text is incorporated into a cache (even via incremental update), the permission requirement stays — ensuring caches that contain extracted text are always properly gated
• Source labels: Artifact viewers now show "Based on AI training data knowledge" or "Based on extracted document text" so you know what each cache contains
• Relative time: Dates in artifact viewers now include relative time (e.g., "2026-02-10 (3d ago)")
• Incremental update indicator: Shows previous coverage when a cache was incrementally updated (e.g., "21% (updated from 6%)")

View/Update Popup for Incremental Actions

X-Ray and Recap buttons now show a View/Update/Cancel popup when a cached result exists, preventing accidental re-runs that cost API tokens.

• Universal: Applies everywhere — Quick Actions panel, Reading Features menu, gestures, and book chat input field action picker
• Smart fallthrough: Falls through to direct execution when no cache exists (first run behaves exactly as before)
• Contextual details: View button shows cached coverage and age (e.g., "View X-Ray (29%, today)"); Update button shows current reading position (e.g., "Update X-Ray (to 45%)")
• Simplified QA panel: Individual "View X-Ray"/"View Analysis" utility buttons replaced with a single "View Artifacts" button that opens the cache picker

Bug Fixes

• Book context missing in Reading Features/Quick Actions: executeBookLevelAction() and executeFileBrowserAction() passed nil as book context, so the chat viewer showed no book metadata at top and "Show Quote" was grayed out — now builds and passes book context string matching the input dialog behavior
• Artifact delete button: Delete button in artifact viewer was hardcoded for summaries only — now works for all artifact types (X-Ray, Analysis, Summary) with dynamic confirmation text (e.g., "Delete this X-Ray?")
• File browser artifact delete: Delete button now works from the file browser (previously required an open book) by passing file path through cache metadata
• X-Ray Full View delete: Delete in Full View now properly closes the X-Ray browser in addition to the viewer

Changelog since v0.17.1: v0.17.1...v0.17.2

KOAssistant v0.17.1 Release Notes

KOAssistant v0.17.1 Release Notes

This is a minor maintenance and bugfix release for v0.17.0. Release notes for v0.17.0 are preserved below.

Bug Fixes

• File browser chats not saving: Book chats started from the file browser (long-press menu) were not being saved — added fallback for document path and book metadata from configuration when ui.document is not available
• "View Artifacts" button in file browser: Fixed button always showing generic "View Artifacts" instead of dynamic name (e.g., "View X-Ray") when only one artifact exists
• "Save to Note" in X-Ray chat: Fixed "Save to Note" button being incorrectly enabled in X-Ray browser's "Chat about this" sessions — stale selection data from prior highlight chats was leaking through
• "Book: Book:" duplication: Fixed doubled "Book:" prefix in chat viewer book context display

Improvements

Artifact Viewer Metadata

• Title bar now shows artifact type, coverage percentage, and book title (e.g., "X-Ray (42%) - Notes From the Underground") — model and date moved out of the cramped title
• Metadata info line displayed at top of content area showing artifact type, coverage, model, and date — always visible regardless of hide quote settings
• Book title now shown in file browser artifact viewers too (previously only available when book was open)

Book Metadata Display

• "Title:" label replaces "Book:" for book context shown at top of chat viewer
• Period-separated format: Metadata items (title, author, language, etc.) now separated by periods on a single line instead of newlines
• Multi-author separator: Multiple authors (stored as newline-separated by KOReader) now displayed as comma-separated (e.g., "Fyodor Dostoevsky, Jane Kentish")
• Chat history continuity: Book context correctly detected when continuing chats from history (no longer falls back to "Highlighted text:" label)

Full Changelog: v0.17.0...v0.17.1

KOAssistant v0.17.0 Release Notes

New Features

Browsable X-Ray

X-Ray results are now structured JSON with a full browsable menu UI, replacing the previous plain markdown output.

• Category menus: Characters, Locations, Themes, Lexicon, Story Arc (fiction) or Key Figures, Core Concepts, Arguments, Terminology, Current Position (non-fiction) — automatically detected
• Character details: AI-generated aliases, connections/relationships, and your highlights mentioning each character
• Chapter Characters: See which characters appear in your current chapter with mention counts
• Cross-category search: Find any entry by name, alias, or description
• Full View: Render the entire X-Ray as markdown in the chat viewer (with export)
• Chat about this: Tap any entry to launch a follow-up book chat about that character, theme, or concept — with irrelevant actions (book text, annotations, notebook) automatically filtered out
• Text selection: Dictionary lookup on 1-3 words, clipboard copy on 4+ (matches chat viewer behavior)
• Dynamic name truncation: Menu descriptions are truncated to fit available space, ensuring character names are always fully visible
• Emoji category icons (optional): Visual indicators per category when emoji icons are enabled
• Backward compatible: Legacy markdown caches fall back to text viewer automatically

One-Tap Auto-Update

Update KOAssistant directly from the release notes viewer — no manual file management needed. This will be usable from the next update.

• Update Now button appears in the release notes viewer when a new version is available
• Downloads the release zip, extracts to a staging directory, verifies the new version, and atomically swaps the plugin directory
• User files preserved automatically: API keys, configuration, custom actions, custom behaviors and domains — all restored after update
• Rollback on failure: If anything goes wrong during the swap, the backup is restored automatically
• Git-aware: Detects .git directory and disables auto-update for developer installs (previously blocked all desktop installs)
• Works on Android and desktop KOReader

Data Access Indicators

See at a glance what sensitive data each action accesses, directly in the action name. See the README for how to enable Emoji UI Fonts in KOReader.

• Emoji suffixes: 📄 (document text/caches), 📝 (annotations), 📓 (notebook), 🌐 (web search)
• Shown in: Action Manager, Reading Features menu, Quick Actions, highlight/dictionary menus, file browser buttons
• Independent setting: Separate from Emoji Menu Icons — enable either or both (Settings → Display Settings → Emoji Data Access Indicators)

Chat Viewer for Notebooks

Notebooks now open in the chat viewer by default instead of KOReader's reader.

• Provides Copy, Export, MD/TXT toggle, Open in Reader, and Edit buttons in one place
• Setting under Notebooks → Viewer Mode to switch back to KOReader reader if preferred

Graceful Degradation for Text Extraction Actions

Actions that use document text now work meaningfully even when text extraction is disabled (the default).

• New conditional placeholder {text_fallback_nudge} guides the AI to use its training knowledge of the work, with an honesty guard for unrecognized titles
• Applied to 8 actions: Explain/Analyze in Context, Key Arguments, Discussion Questions, Generate Quiz, Analyze/Summarize Document, Extract Insights
• Invisible when document text is present — only activates as a fallback
• X-Ray and Recap keep their own specialized fallback behavior

Context Usage Warning

A one-time dismissable warning when a follow-up message exceeds ~50K estimated tokens, alerting that each reply resends the full conversation history. Helps avoid unexpectedly large API costs in long conversations.

Improvements

Text Extraction Defaults

• Default raised to 1M chars / 500 PDF pages (was 250K / 250) — covers full novels without truncation
• Maximum raised to 2M chars / 1,000 PDF pages (was 1M / 500)
• Previous defaults only covered ~40-60% of a typical novel; partial extractions produce worse results than letting the model's context window be the real limit

Actions & Prompts

• Explain/Analyze in Context switched to full document extraction ({full_document_section}) for consistency with their Smart variants — only X-Ray and Recap remain spoiler-safe with position-limited extraction
• Recap output token limit bumped to 8K (was 4K)
• Individual artifact buttons in Quick Actions: "View X-Ray" and "View Analysis" with progress percentage replace the generic "View Artifacts" button
• Export button added to X-Ray Full View (chat viewer simple_view mode)

Metadata

• Use KOReader's merged metadata (ui.doc_props) instead of raw file metadata — respects user edits from the Book Info dialog, with automatic filename fallback

Links in Chat Viewer

• Delegate external link handling to KOReader's ReaderLink when a book is open — gives access to all registered plugin buttons (Wallabag, Wikipedia, etc.) instead of hardcoded options

Emoji Icons Expansion

• Conditional emoji icons extended to: settings menu top actions (💬 Chat, 📜 History, 📓 Notebooks, 📖 Reading Features), config items (🔗 Provider, 🤖 Model, 🔑 Keys), section submenus, chat history prefixes, chat viewer, and notebook browser
• Quick Settings: "Extended Thinking" renamed to "Anthropic/Gemini Reasoning"

Translation Fixes

• (Smart) suffix and trailing spaces moved outside _() translation markers for correct localization

Bug Fixes

• X-Ray crash: Fixed crash when AI returns strings instead of arrays for fields like aliases, connections, or conflicts — new ensure_array() helper normalizes values across 12 access points
• X-Ray browser navigation: Replaced close_callback (fired on every menu tap) with onCloseWidget (fires only on actual close), fixing broken back arrow navigation and stale menu state
• Settings reset: Fixed missing general_menu_actions and _dismissed_general_menu_actions in reset, and added 12 missing persistent feature keys to the preserve list — prevents losing user language preferences, trusted providers, and other choices during reset
• View Artifacts button: Fixed multiple issues — stale is_general_context flag from previous sessions, incorrect file path lookup via book_metadata.file (always nil after metadata reconstruction), and button placement now in its own dedicated bottom row
• Metadata fallback: Fixed 9 locations using raw document:getProps() instead of user-edited doc_props
• Link dialog: Fixed hardcoded Wallabag-only link handling — now delegates to KOReader's full plugin ecosystem

Testing

• 23 new unit tests for auto-update helper functions (verify, preserve, restore, backup path, zip URL extraction)
• 83 new prompt building tests covering text fallback nudge, context usage estimation, and template integration
• 27 new template tests for conditional placeholder behavior

Also in v0.16.x (if updating from v0.15.x):

v0.16.0/v0.16.1 added web search per-action controls (Anthropic/Gemini/OpenRouter), file browser action pinning, dictionary lookup on text selection in chat viewer, View Artifacts in action input dialog, new actions (ELI5, Key Arguments Smart, Generate Quiz, Fact Check, Current Context, Book Reviews), emoji icons setting, Open Last Chat, significant performance improvements (TCP warmup, deferred chat index, non-blocking update check), full-document prompt rewrites, and many bug fixes including the critical replace_placeholder() infinite loop fix.

See the full v0.16.0 release notes and v0.16.1 release notes for details.

Full Changelog: v0.16.1...v0.17.1