Quilltap v2.9.0 Release Notes

Highlights

400%+ Faster Chat Responses — Compression caching overhaul eliminates the wait for context compression. When pre-compression isn't ready, Quilltap falls back to the previous cache with a dynamically expanded context window—trading a few extra tokens for dramatically faster response times.

Chat State — Persistent JSON storage attached to chats and projects, enabling game mechanics, inventories, character stats, and any structured data that should survive across sessions. Path syntax supports dot notation and array indexing. Underscore-prefixed keys are protected from AI modification.

RNG Tool & Auto-Detection — Built-in random number generation for dice rolls, coin flips, and "spin the bottle" participant selection. Dice notation in messages (e.g., "2d6", "d20") is detected and executed automatically—when a character says "I roll 2d6," the dice actually roll.

AI Wizard Enhancements — Character generation wizard now streams real-time progress, generates names, and accepts document uploads (text, Markdown, PDF) as source material for character creation.

Built-in Help Search — LLMs can now search Quilltap's documentation during conversations via the search_help tool, helping users understand features without leaving their chat.

Complete Backup System — Backup archives now include plugin configurations and npm-installed plugins, enabling full system restoration from a single ZIP file.

Major Features

400%+ Faster Chat Responses

Pre-compression now triggers immediately after assistant message save, not after memory extraction and context summary checks (previously 68+ second delay)
When async pre-compression isn't ready, falls back to previous cache instead of waiting
Dynamic window calculation ensures no messages are lost when using older cache
Trade-off: slightly more tokens (larger context window) for significantly faster response time
Compression cache now persists to database, surviving server restarts
Cache lookup order: in-memory (fastest) → database (survives restarts) → sync compression (fallback)
Relaxed cache validation allows up to 50 new messages before requiring fresh compression
System prompt hash validation ensures cache validity
Multi-turn conversations with tool calls (RNG, state, MCP) now properly benefit from caching

Chat State for Persistent JSON Storage

New state field on chats and projects stores arbitrary JSON data
Built-in state LLM tool with fetch/set/delete operations
Path syntax: dot notation (player.health) and array indexing (inventory[0].name)
Inheritance: chat state overrides project state for chats within projects
Protected keys: underscore-prefixed keys (e.g., _notes) cannot be modified by AI
StateEditorModal for viewing and editing state in the UI
State button in chat ToolPalette (database icon)
Project State section in project settings
API endpoints: GET/PUT/DELETE with ?action=get-state/set-state/reset-state

RNG (Random Number Generator) Tool

Built-in rng tool for dice rolls, coin flips, and random participant selection
Supports any die configuration from d2 to d1000
Results are permanent chat messages visible to all characters
Manual invocation via RngDropdown with quick options (d6, d20, 2d6, coin, bottle)
Custom roll interface for arbitrary dice configurations
Uses cryptographically secure random numbers
Auto-detection of patterns in user and assistant messages:
- Dice notation: "2d6", "d20", "3d10"
- Coin flips: "flip a coin"
- Spin the bottle: randomly selects a chat participant
autoDetectRng setting (default: true) can be disabled in Chat Settings
Pending tool results shown as chips in composer before sending

AI Wizard Improvements

Real-time progress — Each field shows checkmark and snippet as it completes via Server-Sent Events
Name generation — Wizard no longer requires a name first; can generate completely random characters
Document upload — New "Upload a document" option accepts .txt, .md, and PDF files as character source material
Streaming endpoint: POST /api/v1/characters?action=ai-wizard-stream

Built-in Help Search Tool

search_help tool allows LLMs to search Quilltap documentation during conversations
Uses semantic search when OPENAI_API_KEY is available, keyword fallback otherwise
Always enabled by default
Pre-computed embeddings loaded from compressed MessagePack bundle (~3-4MB vs. ~24MB JSON)
Whole-document embeddings for better retrieval quality

Complete Backup & Restore

Backup now includes plugin configurations from plugin_configs table
Backup now includes npm-installed plugins from plugins/npm/ directory
Restore recreates plugin configs and extracts npm plugins
Manifest counts include pluginConfigs and npmPlugins
Full system recreation from a single backup file
S3/cloud backup functionality removed; local download only (use external scripts for cloud storage)

Provider Updates

Grok Plugin Migration to xAI Responses API

BREAKING: Migrated from deprecated Chat Completions API to Responses API (/v1/responses)
Uses direct HTTP (fetch) instead of OpenAI SDK for chat
New models: grok-4, grok-4-1-fast (2M context), grok-3, grok-3-mini, grok-2-1212, grok-code-fast-1
Web search uses server-side tools (web_search, x_search) instead of deprecated Live Search API
Image format changed from image_url to input_image
Stateless operation with store: false
Image generation model updated to grok-2-image
Plugin version: 1.0.14

Embedding Service Plugin Architecture

Embedding providers now delegate to plugins via createEmbeddingProvider() factory
EmbeddingProvider interface added to LLMProviderPlugin
New provider classes: OpenAIEmbeddingProvider, OllamaEmbeddingProvider
Built-in TF-IDF provider implemented as LocalEmbeddingProvider
Registry method createEmbeddingProvider() matches createImageProvider() pattern
Removed hardcoded provider handlers from embedding-service.ts
Plugin versions: openai 1.0.16, ollama 1.0.10

Image Provider Enhancements

promptingGuidance field for provider-specific prompting tips
styleInfo field with ImageStyleInfo interface for style/LoRA details and trigger phrases
Chat LLM receives guidance in image generation tool description
Cheap LLM incorporates style trigger phrases when crafting expanded prompts
@quilttap/plugin-types v1.12.0

Plugin Icon System Redesign

Plugins provide SVG data via icon property instead of React components
PluginIconData interface in @quilttap/plugin-types v1.10.0
renderIcon deprecated (kept for backwards compatibility)
Removed React peer dependency from all bundled provider plugins
ProviderIcon component renders SVG with abbreviation fallback

API & Backend

Data Directory Management

New Profile page section shows data directory location, configuration source, and platform
"Open in File Browser" button opens directory in native file explorer (macOS/Windows/Linux)
Copy button for path
Docker environments show guidance about host volume mounts
API endpoint: GET/POST /api/v1/system/data-dir

Native Import/Export Improvements

Character field remapping: defaultConnectionProfileId, defaultImageProfileId, defaultRoleplayTemplateId
Chat participant roleplayTemplateId remapped (preserves plugin template references)
Profile tags reconciled: connection profiles, image profiles, embedding profiles
Roleplay template tags reconciled on import
Memory field remapping: projectId, tags

Middleware Refactoring

createAuthenticatedHandler → createContextHandler
createAuthenticatedParamsHandler → createContextParamsHandler
AuthenticatedContext → RequestContext
withAuth → withContext, withAuthParams → withContextParams
checkOwnership replaced with simpler exists type guard
Legacy aliases maintained for backward compatibility

Performance

Compression Cache Improvements

Pre-compression triggers immediately after assistant message save (not after 68+ second async work)
Runs in parallel with memory extraction
System prompt hash validation for cache retrieval
Debug logging for cache hit/miss reasons
Cache persists to database, surviving server restarts
Lookup order: in-memory → database → sync compression fallback
Relaxed validation: allows up to 50 new messages
Fallback to previous cache when async pre-compression not ready
Dynamic window calculation ensures no messages lost with older cache

Cache Bug Fixes

Fixed invalidation in multi-character chats (was comparing filtered vs. raw event counts)
Multi-turn conversations with tool calls now properly benefit from caching

UI Improvements

Chat Response Status Indicator

Visual indicator shows current processing stage during AI response generation
Stages: compressing (blue), gathering (purple), building (amber), sending (blue), streaming (green), tool_executing (purple)
QuillAnimation for streaming, pulsing icon for other stages
Accessible with role="status" and aria-live="polite"
Respects prefers-reduced-motion

Styling Refinements

User messages have 1.5rem top margin for better visual separation
Tool messages have 1rem vertical margin with qt-chat-message-row-tool class
Dead code removed from avatar-styles.ts, connection-resolver.ts, chat-files-v2.ts
Hard-coded Tailwind colors converted to qt-* utility classes
New qt-border-/30 and hover:qt-bg-/10 opacity variants for status colors

Template Import Fix

"Import from Template" modal now correctly shows templates
Fixed prompt-templates response handling to extract .templates array
Added ?all=true parameter for flattened prompt list

Documentation

Comprehensive User Guides

Projects: Main overview, file management, chat association, character roster, settings
Chats: Overview, multi-character setup, turn manager, participants sidebar, message actions
Startup Wizard: Complete rewrite with provider-specific setup instructions
Page links: Every help file now includes direct link to corresponding app page with tab parameters

Help System Infrastructure

Pre-computed embeddings in gzipped MessagePack (help-bundle.msgpack.gz)
Whole-document embeddings instead of heading-based chunks
npm run build:help generates the bundle
Semantic search via cosine similarity with keyword fallback

API Documentation Updates

Version updated from v2.8 to v2.9
Six new sections: Chat Settings, Models, Files (v1), System Backup & Restore, System Data Directory, System Mount Points
Legacy endpoints marked in Table of Contents
About page updated: new tagline, expanded description, quilttap.ai link, removed authentication references

Bug Fixes

Critical

Temporary backup download failing due to HMR invalidating in-memory storage (moved to globalThis singleton)
User-initiated tool results not sent to LLM (field name mismatch: tool vs. toolName)
Virtualizer positioning bug when messages replaced (now uses message IDs as keys, not indices)
Pending tool results not persisting to database (missing parameter in API route)
LLM responses wrapped in content block format now normalized

Docker

Build failures from npm lockfile issues fixed
npm upgraded in base image to fix "Invalid Version" bug
@quilttap/plugin-types changed from file: reference to npm package
package-lock.json regenerated in Linux container
Deprecated --only=production updated to --omit=dev

Testing

E2E Test Updates

Uses production build for stability
Fresh temp data directory per test run
Removed authentication code (single-user mode)
Updated API routes to /api/v1/ prefix
Removed deprecated persona tests
Retry logic for flaky page loads
Ollama with llama3.2 as default test provider

Refactoring

Tools System

Tools sent with every LLM prompt (removed periodic re-injection logic)
forceToolsOnNextMessage flag retained only for change notifications

Dependencies

@anthropic-ai/sdk upgraded to ^0.72.1
ESLint rule added to catch "Quilttap" misspellings

Removals

S3/cloud backup destination removed from backup dialog
Cloud backups list and selection removed from restore dialog
S3-related backup functions removed
Restore API simplified to file uploads only

Breaking Changes Summary

Grok plugin uses Responses API — Migrated from deprecated Chat Completions API
Plugin icons use SVG data — renderIcon deprecated; React no longer required for icons
S3 backup removed — Local download only; use external scripts for cloud storage

Uh oh!

2.9.0