Project Files
Project Files
| Feature | Description |
|---|---|
| 📁 File System | Read, write, search, and manage files with path validation & backup support |
| 🌐 Web Research | Multi-engine search (DDG, Google, Bing) with automatic fallback |
| 🖥️ Browser Automation | Headless Puppeteer browser with persistent sessions & UI interaction |
| 🐙 Git & GitHub | Full Git operations (including stash/blame) + GitHub API integration |
| 🗃️ Database | Read-only SQLite queries with SQL validation |
| ⏳ Background Commands | Long-running process management and status tracking |
| ⚡ Code Execution | Sandboxed JS/Python + full shell commands (pipes, redirects, env vars) |
| 🔧 Utilities | Clipboard, notifications, system info, memory, session summaries, and environment management |
| 🖼️ Image Processing | OCR (Tesseract.js), screenshots, and image comparison |
| 📊 Vector RAG | Semantic search with vector embeddings for intelligent document retrieval |
| 🎨 UI Generation | Generate and render interactive HTML/CSS/JS components in-browser |
| 🧠 Context Management | Automatic session tracking, decision logging, and memory management |
| 📝 Text Processing | Advanced regex-based text transformations (sed/awk equivalents) |
| 📋 Task Planning | Structured multi-step workflow tools (create_plan, get_plan, update_plan_step) |
list_directory · read_file · read_file_chunked · save_file · replace_text_in_file · insert_at_line · append_file · delete_lines_in_file · make_directory · move_file · copy_file · delete_path · delete_files_by_pattern · find_files · fuzzy_find_local_files · get_file_metadata · change_directory · analyze_project · file_diff · directory_tree · grep_files · find_replace_all
rag_web_content served by the Vector RAG module since v1.9.10)web_search · wikipedia_search · fetch_web_content
browser_open_page · browser_session_control · browser_session_close · preview_html · open_file
Local Operations (isomorphic-git): git_status · git_diff · git_commit · git_log · git_add · git_checkout · git_stash · git_blame
Remote API (GitHub CLI gh): gh_create_issue · gh_list_issues · gh_view_comments · gh_create_pr · gh_list_prs · gh_push
Note: Remote operations require the GitHub CLI to be installed and authenticated (
gh auth login).
query_database
read_document
run_background_command · check_background_command · cancel_background_command
image_to_text · describe_image · screenshot_desktop · compare_images
http_request · http_get_json · http_post_json
rag_index_files · rag_index_pdf · rag_index_docx · rag_index_xlsx · rag_query_vector · rag_clear_index · rag_web_content
generate_ui_component · render_and_preview_ui · extract_ui_data
auto_summarize_context · get_context_memory · search_context · context_summary · delete_context_entry · clear_context_memory · track_important_event · save_session_summary · get_session_summary · save_memory · get_memory · delete_memory
text_transform · text_extract · line_operations · markdown_table_gen
refactor_code · unusedImports
create_plan · get_plan · update_plan_step
run_javascript · run_python · execute_command · run_in_terminal · run_tests
The plugin is installed as an LM Studio plugin. Ensure you have:
gh) — required for remote GitHub operations (Issues, PRs). Install at https://cli.github.com/gh auth login in your terminal once to enable remote operations (gh_create_issue, gh_list_prs, etc.). The plugin will detect authentication status automatically.The plugin uses a comprehensive configuration schema (src/config.ts) which is exposed in LM Studio's settings UI. Key features include:
Comprehensive documentation of security features, threat models, and responsible disclosure of the AI Toolbox plugin. See SECURITY.md for details.
Deep dive into the AI Toolbox plugin's system architecture, design patterns, and internal workflows. See ARCHITECTURE.md for details.
# Install dependencies npm install # Build the project (ESM + CJS via Tsup) npm run build # Run type checking npm run typecheck # Run test suite npm test
Resolved critical grammar parser failure and added defensive error handling for SDK token counting.
Resolved critical grammar parser failure in production — tool count capping now enforced at 25 tools (was 50), minifier properly wired up.
Registered utility tools and cleaned up orphaned gateway pattern code.
backupTools (create_backup, list_backups, restore_backup, delete_backup)cleanupBackupsTool (cleanup_backups)dataVisualizationTools (generate_chart)lineOperations (delete_lines)markdownPreviewTools (markdown_preview)utility config toggle to enable/disable all utility toolsEliminated all any type usage and fixed config resolution for ParsedConfig wrapper.
z.any() with z.unknown() in Zod schemaslatest.timestamp! with latest.timestamp ?? 0PluginConfig object from .get() calls instead of direct property access on ParsedConfig wrapperas unknown as double-cast for @typescript-eslint/parser return typeResolved critical token limit hardcoding, fixed JSON serialization crashes, and added comprehensive safety guardrails to line_operations tool.
getContextLength() API (accurately detects up to 224k+ tokens)summaryModel configuration approachResolved recurring issues where LLMs inserted content at wrong lines due to stale line numbers.
Three-layer defense-in-depth strategy:
| Layer | Parameter | Purpose |
|---|---|---|
| Content-Aware Insertion | insert_after_pattern / insert_before_pattern | Find insertion point by searching file content instead of trusting line numbers |
| Line Fingerprinting | verify_before_insert | Content expected at target_line — blocks operation if mismatch and shows actual context |
| Bounds Validation | Auto-detection + limits | Rejects out-of-range lines, multi-line content splitting, large insert blocking (>5 lines) |
Example usage:
// Pattern-based (line-number-agnostic): line_operations(file_name, operation: "insert", insert_after_pattern: "if (width <= 0 || height <= 0)", content: "// fix" ) // Verification-based (prevents drift errors): line_operations(file_name, operation: "insert", target_line: 84, content: "// fix", verify_before_insert: "return;" // Content expected at line 84 )
Impact: All guardrails tested and verified — 9/9 test scenarios passed with zero regressions.
Resolved critical token undercounting bug caused by incomplete message content extraction when LM Studio SDK v1.x returns array-based content blocks or ChatMessage objects.
ContextGuard.countTokens() now properly extracts text from arrays of content blocks [{"type": "text", "text": "..."}] instead of stringifying entire arrays.getText() method or .text property before JSON serialization for structured message objects@typescript-eslint/no-base-to-string error with explicit type checks and scoped suppressionFixed critical performance issue where grep_files searched ALL directories including node_modules, .git, and build artifacts.
DEFAULT_EXCLUDED_DIRS Set in walkDirectory() function within src/tools/fileSystemTools.tsnode_modules, .git, dist, build, .next, .nuxt, __pycache__, .cache, vendor, .vscode, .idea, .vsinclude pattern (backward compatible)Architectural overhaul of tool registration system — replaced repetitive gating logic with a clean, maintainable registry pattern using closures.
TOOL_REGISTRIES) containing 20 entriesconfig, stateManager, and backgroundCommandManager at definition time via arrow functions, eliminating parameter-passing complexityany[] types, replaced with typed closures (() => Tool[]) that satisfy strict ESLint rulesfor...of iteration replaces scattered conditional blocks — adds tools based on config keys or GOD MODE bypassResolved critical token undercounting bug caused by incomplete message content extraction when LM Studio SDK v1.x returns array-based content blocks.
ContextGuard.countTokens() now properly extracts text from arrays of content blocks, ChatMessage objects.Resolved critical TypeError: Cannot read properties of undefined (reading 'length') crash in promptPreprocessor.ts.
historyTextLength.Resolved critical token counting inaccuracy and missing checkpoint prompt injection issues.
.content casting with LM Studio's native history API (getLength(), at(i), getText()).countTokens() × 65 to History Text Length × 0.24 ratio — matches sidebar exactly.Added three new tools for creating, tracking, and updating execution plans with persistent storage.
create_plan — Create execution plans with goal + ordered steps (1–30 steps). Returns planId, goal, stepCount.get_plan — Return active plan details including step statuses, completion %, elapsed time.update_plan_step — Update step status per state machine rules (pending→in_progress→done, any→blocked).Applied five critical fixes: token ratio calibration, missing config exports, test console suppression, insert_at_line read-back drift detection.
contextGuard.ts and promptPreprocessor.ts. Effective ratio ~0.275 with +10% buffer — matches LM Studio sidebar within <0.3% deviation.validateConfig() and isToolEnabled() to src/config.ts public API.Added explicit LLM-accessible tools for discovering and restoring from .bak backup files created by file-modifying operations.
restore_from_bak(file_name) — Restores any file from its .bak backup; scans working directory, copies back original, deletes .bak. Returns list of available backups if none found.list_available_bak_backups() — Scans for all .bak files and returns structured data: {file, backupFile, sizeBytes} array.backupMessage field announcing the .bak location to LLM.Resolved Jest moduleNameMapper catch-all regex conflict with tool imports and synchronized version references across all documentation files.
./tools/index.js) and attempted to resolve them to non-existent mock files. Reverted to individual tool imports for Jest compatibility.Three architectural improvements to the memory system with context isolation and intelligent retrieval.
MemoryScope type (global/project/session) to prevent cross-project memory bleedResolved critical Regex Denial of Service (ReDoS) vulnerability in grep_files AND completed comprehensive RAG system overhaul with new indexing tools for PDF, DOCX, and XLSX formats.
hasTopLevelAlternation() scanner tracking parenthesis depth to catch \| at root levelRegExp[] branches — each tested separately with early-exit, eliminating cross-branch backtracking in V8's NFA enginerag_index_pdf, rag_index_docx, rag_index_xlsx) expanding Vector RAG from 4 → 7 total toolspdf-parse, chunks by page boundary with ~300 words/chunk — traceable results per page number; verified against 25MB/1690-page programming guide without OOM/crashmammoth dependency for DOCX extraction — word-bounded chunks (default 300 words, 50 overlap); semantic search working correctlyxlsx ^0.18.5 dependency; extracts all sheets as row arrays with configurable sheet-name prefix; verified programmatic smoke test showing correct ranking of API vs Test Data sheetsvectorRagTools.ts: Resolved 4 issues (unused catch param, unsafe return cast, dead eslint-disable directives) — zero errors/warnings after fixgrep_files-specific tests — zero regressionsResolved unused eslint-disable directives and eliminated implicit any assignments in HTTP client tools through explicit type annotations.
src/tools/httpClientTools.ts and src/tools/networkToolsRegistry.ts, eslint-disable-next-line @typescript-eslint/no-unsafe-assignment comments were flagged as unused because assigning response.json() to variables with explicit : unknown type is already safe per TypeScript/ESLint rules.unknown annotations: Replaced implicit any assignments (const data = await response.json();) with typed declarations (const data: unknown = await response.json();) across all HTTP response parsing paths — 10 warnings resolved total.Prior to this fix, ESLint's @typescript-eslint/no-unsafe-assignment rule flagged assignments where the source expression was any (from response.json()) and the target variable was implicitly typed as any. TypeScript infers any when no explicit type annotation is provided, which defeats compile-time safety checks. The previous session added suppression directives with justifications, but ESLint correctly reported them as unused because assigning any → explicit unknown satisfies the rule without needing suppression.
no-unsafe-assignment warnings resolved across both files: unknown annotations force downstream consumers to perform type guards or assertions before using HTTP response payloadsFixed critical get_session_summary() disk fallback bug + applied 14 comprehensive fixes across P0-P3 severity levels for context management tools.
get_session_summary() reads .msgpack as ContextEntry[] and parses JSON content from summaryEntry.content or falls back to legacy text format — prevents data loss on plugin reloadaddEntry() now merges updated data into existing entry instead of creating duplicates via unshift()getRecentEntries() and searchEntries() prune expired entries inline after load → save (single I/O)generateId() uses crypto.randomBytes(9) (72-bit entropy) instead of Math.random().substr(2, 9)require('crypto') with static ESM import import * as crypto from 'crypto'Five major architectural improvements inspired by graphify repository analysis — confidence-tagged results, hub-exclusion clustering, project auto-detection, context tier provenance, and cluster-aware tool priority ranking.
src/types/confidenceTypes.ts): Typed metadata (EXTRACTED | INFERRED | AMBIGUOUS) with provenance tracking for all tool outputs — enables LLMs to distinguish deterministic results from semantic inferences.src/utils/hubExclusionClustering.ts): Louvain community detection with hub-exclusion for architectural transparency; identifies high-degree modules, calculates cluster density/modularity, and reattaches hubs via majority-vote. 83 tests covering graph construction, convergence, and edge cases.src/projectAutoDetect.ts): Automatically detects and registers projects in the cross-project registry when searches return empty results; uses confidence scoring (package.json +0.4, src/ +0.3) with name normalization for fuzzy matching. (⚠️ Superseded in v1.9.8 — silent auto-registration removed, explicit confirmation required.)src/contextTiers.ts): Typed _origin: 'ast' | 'semantic' markers for tier-scoped context replacement — prevents silent overwrites of unchanged nodes during incremental updates.src/tools/toolPriority.ts): Five-tier priority ranking (Critical → Background) with hub-exclusion clustering integration; ensures architecturally important modules are retained first when grammar parser limits require tool pruning.Replaced all child_process.exec() calls with explicit shell spawning via spawn(cmd.exe /c, ...) in gitGithubTools.ts. Zero behavioral changes.
exec import + promisify: Replaced with single import { spawn } from 'child_process'safeExec() helper function: Explicit shell spawning using cmd.exe /c (Windows) or /bin/sh -c (Unix/macOS) — never uses { shell: true }, avoiding Node.js DEP0190 warninggit diff, git commit, git checkout -b, git push, git stash push/pop/drop/list, git blame now use safeExec() instead of execPromise()atomicWrite Utility & Full Async ConversionEliminated all synchronous file writes from the codebase; introduced shared crash-resilient atomic write utility with randomized temp filenames and rollback-on-failure protection.
src/utils/atomicWrite.ts)atomicWrite utility: Randomized temporary filenames via crypto.randomBytes(9) — prevents collisions, survives process crashes. Binary file support via dedicated atomicWriteBinaryFile().refactorCodeTools & recodeEngine: Source code protection — failed AST transformations automatically restore original file from .bak backup.writeFileSync/renameSync eliminated from src/tools/.atomicWriteBinaryFile() uses raw buffer writes — image/chart output preserves exact binary content.Three major fixes: eliminated silent auto-registration of wrong project paths, hang prevention for grep_files/find_replace_all, and elimination of the "project not found" clarification loop via Step 0.7 keyword detection + lazy registry sync.
src/index.ts, src/projectAutoDetect.ts)main() called initializeProjectDetection(cwd) unconditionally during plugin startup → silently registered whatever directory it found instead of the actual project path.index.ts. Added explanatory comment documenting that projects must be registered explicitly via the register_project tool.explicitConfirmation: boolean = false parameter to autoDetectAndRegister() and searchWithAutoRegister() — both now block registration when flag is not set to true.initializeProjectDetection() marked as deprecated; no longer calls any registration logic.src/tools/fileSystemTools.ts, src/security.ts)max_depth parameter (default: 10, range: 1–50) to both tools with depth enforcement in walkDirectory/walkDir — prevents infinite recursion into nested directories.MAX_LINES_PER_FILE = 5000 limit inside file processing loops — prevents hanging on large files.isSafeRegex(): Added quantifier count check (>5 returns false) and consecutive quantified character class detection ([[^]]+]+[+*]) to catch additional ReDoS patterns.src/promptPreprocessor.ts, src/tools/contextManagementTools.ts) — added 2026-08-17 (v1.9.8+)search_projects results and a clarification loop.promptPreprocessor.ts): detectProjectKeyword() reads project_registry.json, fuzzy-matches message words against registered projects (hyphen↔underscore normalization), and injects a confirmation prompt before falling through to directory-path detection or RAG.contextManagementTools.ts): _syncFromSessionMemory() scans .ai_toolbox_memory.msgpack for project_path fields and auto-registers missing projects — called lazily inside search_projects / get_project_info, so no startup overhead.register_project tool call with confirmed path — no accidental registration of wrong/stale paths.max_depth and MAX_LINES_PER_FILE=5000 prevent infinite recursion and large-file hangs in grep_files/find_replace_all.search_projects/get_project_info without manual re-registration.register_project (confirmed path) remains the primary registration method; auto-sync is additive.Deadline-based hard limits for grep_files (escape-aware alternation splitting, partial results with aborted flag), mid-loop per-tool token deltas so thresholds fire inside long tool loops, and a live | chat used ≈ N tok field in [AutoTracker] [DELTA] lines.
src/tools/fileSystemTools.ts): escape-aware top-level alternation splitting + real deadline-based hard stops on the sync regex loop. New limits: GREP_SCAN_DEADLINE_MS=15000, MAX_LINE_CHARS_REGEX_MODE=20000 (long lines skipped in regex mode), PER_REGEX_TIMEOUT_MS=500 (abandon-and-continue per candidate), single-file backstop via Promise.race at deadline+5 s; over-cap files reported in skipped_files.src/tokenStatsManager.ts + 4 further source files): every tool result is measured into a running per-turn delta — threshold/compression decisions now evaluate history count + deltas instead of waiting for the next full count.[AutoTracker] [DELTA] lines append | chat used ≈ N tok, where N = turn-start TokenCheck baseline + mid-loop estimate (nested semantics: tool delta ⊆ turn total ⊆ chat used; field omitted when the ContextGuard recount fails).[TokenCheck] log values rounded via Math.round; en-US locale pins for model-facing strings.grep_files can no longer block indefinitely — worst case is deadline + 5 s with partial results flagged aborted: true.Bounded every web/RAG allocation path against plugin-host heap exhaustion and terminated the vector-RAG chunking loop that could spin forever on poison-length documents. Version stays at v1.9.10 — no bump.
rag_web_content registration removed (src/tools/webResearchTools.ts): keyword-based placeholder implementation deleted — tool now served exclusively by the real-RAG version in vectorRagTools.ts; LM Studio shows exactly one entry (dedup invariant: 1× per dist bundle).src/tools/fileSystemTools.ts): line-cap skip messages downgraded console.warn → console.log ([INFO], not [ERROR] in dev logs — already reported via skipped_files).src/performanceUtils.ts + web/HTTP tools): 250K–500K char budgets now gate fetch_web_content, all three search-engine fallbacks, the five HTTP-client body reads, and wikipedia_search; every fetchWithRetry attempt is time-bounded (30 s AbortController); new [HEAP-GUARD] watchdog logs the suspect tool name if heap usage crosses 1 GB before a crash.src/tools/vectorRagTools.ts): soft 250K char cap (oversized pages → success:true + truncated:true with usable partial chunks), HTML markup stripped via html-to-text before chunking/embedding, top-5 cosine-ranked chunks in the result payload.src/tools/vectorRagTools.ts): chunkText / chunkDocxText / chunkPdfText enforce strict forward progress (startIndex = Math.max(endIndex, startIndex + 1)) — eliminates the deterministic V8 OOM loop where certain word-count remainders stalled the window start at a fixed point near end-of-text.tests/vectorRagTools.ragWebContent.test.ts; shared-mock isolation reset in tests/webResearchTools.test.ts (beforeEach) closed the last order-dependent failure — full Jest suite green (user-verified 2026-08-25).rag_web_content tool entry in LM Studio's UI; deterministic dispatch to the real-RAG implementation.| Package | Version | Purpose |
|---|---|---|
@lmstudio/sdk | ^1.5.0 | Core SDK for LM Studio plugin development |
@dqbd/tiktoken | ^1.0.22 | Accurate token counting for ContextGuard |
puppeteer | ^24.0.0 | Browser automation |
isomorphic-git | ^1.38.6 | Pure JS Git operations (migrated from simple-git in v1.5.25) |
sharp | ^0.33.5 | Image processing |
tesseract.js | ^7.0.0 | OCR engine |
pdf-parse | ^1.1.1 | PDF document parsing |
mammoth | ^1.6.0 | DOCX document parsing |
xlsx | ^0.18.5 | XLS/XLSX spreadsheet parsing |
archiver | ^8.0.0 | ZIP archive creation |
unzipper | ^0.12.3 | ZIP extraction |
zod | ^3.25.0 | Runtime type validation |
MIT License. See LICENSE for details.
| Feature | Description |
|---|---|
| 📁 File System | Read, write, search, and manage files with path validation & backup support |
| 🌐 Web Research | Multi-engine search (DDG, Google, Bing) with automatic fallback |
| 🖥️ Browser Automation | Headless Puppeteer browser with persistent sessions & UI interaction |
| 🐙 Git & GitHub | Full Git operations (including stash/blame) + GitHub API integration |
| 🗃️ Database | Read-only SQLite queries with SQL validation |
| ⏳ Background Commands | Long-running process management and status tracking |
| ⚡ Code Execution | Sandboxed JS/Python + full shell commands (pipes, redirects, env vars) |
| 🔧 Utilities | Clipboard, notifications, system info, memory, session summaries, and environment management |
| 🖼️ Image Processing | OCR (Tesseract.js), screenshots, and image comparison |
| 📊 Vector RAG | Semantic search with vector embeddings for intelligent document retrieval |
| 🎨 UI Generation | Generate and render interactive HTML/CSS/JS components in-browser |
| 🧠 Context Management | Automatic session tracking, decision logging, and memory management |
| 📝 Text Processing | Advanced regex-based text transformations (sed/awk equivalents) |
| 📋 Task Planning | Structured multi-step workflow tools (create_plan, get_plan, update_plan_step) |
list_directory · read_file · read_file_chunked · save_file · replace_text_in_file · insert_at_line · append_file · delete_lines_in_file · make_directory · move_file · copy_file · delete_path · delete_files_by_pattern · find_files · fuzzy_find_local_files · get_file_metadata · change_directory · analyze_project · file_diff · directory_tree · grep_files · find_replace_all
rag_web_content served by the Vector RAG module since v1.9.10)web_search · wikipedia_search · fetch_web_content
browser_open_page · browser_session_control · browser_session_close · preview_html · open_file
Local Operations (isomorphic-git): git_status · git_diff · git_commit · git_log · git_add · git_checkout · git_stash · git_blame
Remote API (GitHub CLI gh): gh_create_issue · gh_list_issues · gh_view_comments · gh_create_pr · gh_list_prs · gh_push
Note: Remote operations require the GitHub CLI to be installed and authenticated (
gh auth login).
query_database
read_document
run_background_command · check_background_command · cancel_background_command
image_to_text · describe_image · screenshot_desktop · compare_images
http_request · http_get_json · http_post_json
rag_index_files · rag_index_pdf · rag_index_docx · rag_index_xlsx · rag_query_vector · rag_clear_index · rag_web_content
generate_ui_component · render_and_preview_ui · extract_ui_data
auto_summarize_context · get_context_memory · search_context · context_summary · delete_context_entry · clear_context_memory · track_important_event · save_session_summary · get_session_summary · save_memory · get_memory · delete_memory
text_transform · text_extract · line_operations · markdown_table_gen
refactor_code · unusedImports
create_plan · get_plan · update_plan_step
run_javascript · run_python · execute_command · run_in_terminal · run_tests
The plugin is installed as an LM Studio plugin. Ensure you have:
gh) — required for remote GitHub operations (Issues, PRs). Install at https://cli.github.com/gh auth login in your terminal once to enable remote operations (gh_create_issue, gh_list_prs, etc.). The plugin will detect authentication status automatically.The plugin uses a comprehensive configuration schema (src/config.ts) which is exposed in LM Studio's settings UI. Key features include:
Comprehensive documentation of security features, threat models, and responsible disclosure of the AI Toolbox plugin. See SECURITY.md for details.
Deep dive into the AI Toolbox plugin's system architecture, design patterns, and internal workflows. See ARCHITECTURE.md for details.
# Install dependencies npm install # Build the project (ESM + CJS via Tsup) npm run build # Run type checking npm run typecheck # Run test suite npm test
Resolved critical grammar parser failure and added defensive error handling for SDK token counting.
Resolved critical grammar parser failure in production — tool count capping now enforced at 25 tools (was 50), minifier properly wired up.
Registered utility tools and cleaned up orphaned gateway pattern code.
backupTools (create_backup, list_backups, restore_backup, delete_backup)cleanupBackupsTool (cleanup_backups)dataVisualizationTools (generate_chart)lineOperations (delete_lines)markdownPreviewTools (markdown_preview)utility config toggle to enable/disable all utility toolsEliminated all any type usage and fixed config resolution for ParsedConfig wrapper.
z.any() with z.unknown() in Zod schemaslatest.timestamp! with latest.timestamp ?? 0PluginConfig object from .get() calls instead of direct property access on ParsedConfig wrapperas unknown as double-cast for @typescript-eslint/parser return typeResolved critical token limit hardcoding, fixed JSON serialization crashes, and added comprehensive safety guardrails to line_operations tool.
getContextLength() API (accurately detects up to 224k+ tokens)summaryModel configuration approachResolved recurring issues where LLMs inserted content at wrong lines due to stale line numbers.
Three-layer defense-in-depth strategy:
| Layer | Parameter | Purpose |
|---|---|---|
| Content-Aware Insertion | insert_after_pattern / insert_before_pattern | Find insertion point by searching file content instead of trusting line numbers |
| Line Fingerprinting | verify_before_insert | Content expected at target_line — blocks operation if mismatch and shows actual context |
| Bounds Validation | Auto-detection + limits | Rejects out-of-range lines, multi-line content splitting, large insert blocking (>5 lines) |
Example usage:
// Pattern-based (line-number-agnostic): line_operations(file_name, operation: "insert", insert_after_pattern: "if (width <= 0 || height <= 0)", content: "// fix" ) // Verification-based (prevents drift errors): line_operations(file_name, operation: "insert", target_line: 84, content: "// fix", verify_before_insert: "return;" // Content expected at line 84 )
Impact: All guardrails tested and verified — 9/9 test scenarios passed with zero regressions.
Resolved critical token undercounting bug caused by incomplete message content extraction when LM Studio SDK v1.x returns array-based content blocks or ChatMessage objects.
ContextGuard.countTokens() now properly extracts text from arrays of content blocks [{"type": "text", "text": "..."}] instead of stringifying entire arrays.getText() method or .text property before JSON serialization for structured message objects@typescript-eslint/no-base-to-string error with explicit type checks and scoped suppressionFixed critical performance issue where grep_files searched ALL directories including node_modules, .git, and build artifacts.
DEFAULT_EXCLUDED_DIRS Set in walkDirectory() function within src/tools/fileSystemTools.tsnode_modules, .git, dist, build, .next, .nuxt, __pycache__, .cache, vendor, .vscode, .idea, .vsinclude pattern (backward compatible)Architectural overhaul of tool registration system — replaced repetitive gating logic with a clean, maintainable registry pattern using closures.
TOOL_REGISTRIES) containing 20 entriesconfig, stateManager, and backgroundCommandManager at definition time via arrow functions, eliminating parameter-passing complexityany[] types, replaced with typed closures (() => Tool[]) that satisfy strict ESLint rulesfor...of iteration replaces scattered conditional blocks — adds tools based on config keys or GOD MODE bypassResolved critical token undercounting bug caused by incomplete message content extraction when LM Studio SDK v1.x returns array-based content blocks.
ContextGuard.countTokens() now properly extracts text from arrays of content blocks, ChatMessage objects.Resolved critical TypeError: Cannot read properties of undefined (reading 'length') crash in promptPreprocessor.ts.
historyTextLength.Resolved critical token counting inaccuracy and missing checkpoint prompt injection issues.
.content casting with LM Studio's native history API (getLength(), at(i), getText()).countTokens() × 65 to History Text Length × 0.24 ratio — matches sidebar exactly.Added three new tools for creating, tracking, and updating execution plans with persistent storage.
create_plan — Create execution plans with goal + ordered steps (1–30 steps). Returns planId, goal, stepCount.get_plan — Return active plan details including step statuses, completion %, elapsed time.update_plan_step — Update step status per state machine rules (pending→in_progress→done, any→blocked).Applied five critical fixes: token ratio calibration, missing config exports, test console suppression, insert_at_line read-back drift detection.
contextGuard.ts and promptPreprocessor.ts. Effective ratio ~0.275 with +10% buffer — matches LM Studio sidebar within <0.3% deviation.validateConfig() and isToolEnabled() to src/config.ts public API.Added explicit LLM-accessible tools for discovering and restoring from .bak backup files created by file-modifying operations.
restore_from_bak(file_name) — Restores any file from its .bak backup; scans working directory, copies back original, deletes .bak. Returns list of available backups if none found.list_available_bak_backups() — Scans for all .bak files and returns structured data: {file, backupFile, sizeBytes} array.backupMessage field announcing the .bak location to LLM.Resolved Jest moduleNameMapper catch-all regex conflict with tool imports and synchronized version references across all documentation files.
./tools/index.js) and attempted to resolve them to non-existent mock files. Reverted to individual tool imports for Jest compatibility.Three architectural improvements to the memory system with context isolation and intelligent retrieval.
MemoryScope type (global/project/session) to prevent cross-project memory bleedResolved critical Regex Denial of Service (ReDoS) vulnerability in grep_files AND completed comprehensive RAG system overhaul with new indexing tools for PDF, DOCX, and XLSX formats.
hasTopLevelAlternation() scanner tracking parenthesis depth to catch \| at root levelRegExp[] branches — each tested separately with early-exit, eliminating cross-branch backtracking in V8's NFA enginerag_index_pdf, rag_index_docx, rag_index_xlsx) expanding Vector RAG from 4 → 7 total toolspdf-parse, chunks by page boundary with ~300 words/chunk — traceable results per page number; verified against 25MB/1690-page programming guide without OOM/crashmammoth dependency for DOCX extraction — word-bounded chunks (default 300 words, 50 overlap); semantic search working correctlyxlsx ^0.18.5 dependency; extracts all sheets as row arrays with configurable sheet-name prefix; verified programmatic smoke test showing correct ranking of API vs Test Data sheetsvectorRagTools.ts: Resolved 4 issues (unused catch param, unsafe return cast, dead eslint-disable directives) — zero errors/warnings after fixgrep_files-specific tests — zero regressionsResolved unused eslint-disable directives and eliminated implicit any assignments in HTTP client tools through explicit type annotations.
src/tools/httpClientTools.ts and src/tools/networkToolsRegistry.ts, eslint-disable-next-line @typescript-eslint/no-unsafe-assignment comments were flagged as unused because assigning response.json() to variables with explicit : unknown type is already safe per TypeScript/ESLint rules.unknown annotations: Replaced implicit any assignments (const data = await response.json();) with typed declarations (const data: unknown = await response.json();) across all HTTP response parsing paths — 10 warnings resolved total.Prior to this fix, ESLint's @typescript-eslint/no-unsafe-assignment rule flagged assignments where the source expression was any (from response.json()) and the target variable was implicitly typed as any. TypeScript infers any when no explicit type annotation is provided, which defeats compile-time safety checks. The previous session added suppression directives with justifications, but ESLint correctly reported them as unused because assigning any → explicit unknown satisfies the rule without needing suppression.
no-unsafe-assignment warnings resolved across both files: unknown annotations force downstream consumers to perform type guards or assertions before using HTTP response payloadsFixed critical get_session_summary() disk fallback bug + applied 14 comprehensive fixes across P0-P3 severity levels for context management tools.
get_session_summary() reads .msgpack as ContextEntry[] and parses JSON content from summaryEntry.content or falls back to legacy text format — prevents data loss on plugin reloadaddEntry() now merges updated data into existing entry instead of creating duplicates via unshift()getRecentEntries() and searchEntries() prune expired entries inline after load → save (single I/O)generateId() uses crypto.randomBytes(9) (72-bit entropy) instead of Math.random().substr(2, 9)require('crypto') with static ESM import import * as crypto from 'crypto'Five major architectural improvements inspired by graphify repository analysis — confidence-tagged results, hub-exclusion clustering, project auto-detection, context tier provenance, and cluster-aware tool priority ranking.
src/types/confidenceTypes.ts): Typed metadata (EXTRACTED | INFERRED | AMBIGUOUS) with provenance tracking for all tool outputs — enables LLMs to distinguish deterministic results from semantic inferences.src/utils/hubExclusionClustering.ts): Louvain community detection with hub-exclusion for architectural transparency; identifies high-degree modules, calculates cluster density/modularity, and reattaches hubs via majority-vote. 83 tests covering graph construction, convergence, and edge cases.src/projectAutoDetect.ts): Automatically detects and registers projects in the cross-project registry when searches return empty results; uses confidence scoring (package.json +0.4, src/ +0.3) with name normalization for fuzzy matching. (⚠️ Superseded in v1.9.8 — silent auto-registration removed, explicit confirmation required.)src/contextTiers.ts): Typed _origin: 'ast' | 'semantic' markers for tier-scoped context replacement — prevents silent overwrites of unchanged nodes during incremental updates.src/tools/toolPriority.ts): Five-tier priority ranking (Critical → Background) with hub-exclusion clustering integration; ensures architecturally important modules are retained first when grammar parser limits require tool pruning.Replaced all child_process.exec() calls with explicit shell spawning via spawn(cmd.exe /c, ...) in gitGithubTools.ts. Zero behavioral changes.
exec import + promisify: Replaced with single import { spawn } from 'child_process'safeExec() helper function: Explicit shell spawning using cmd.exe /c (Windows) or /bin/sh -c (Unix/macOS) — never uses { shell: true }, avoiding Node.js DEP0190 warninggit diff, git commit, git checkout -b, git push, git stash push/pop/drop/list, git blame now use safeExec() instead of execPromise()atomicWrite Utility & Full Async ConversionEliminated all synchronous file writes from the codebase; introduced shared crash-resilient atomic write utility with randomized temp filenames and rollback-on-failure protection.
src/utils/atomicWrite.ts)atomicWrite utility: Randomized temporary filenames via crypto.randomBytes(9) — prevents collisions, survives process crashes. Binary file support via dedicated atomicWriteBinaryFile().refactorCodeTools & recodeEngine: Source code protection — failed AST transformations automatically restore original file from .bak backup.writeFileSync/renameSync eliminated from src/tools/.atomicWriteBinaryFile() uses raw buffer writes — image/chart output preserves exact binary content.Three major fixes: eliminated silent auto-registration of wrong project paths, hang prevention for grep_files/find_replace_all, and elimination of the "project not found" clarification loop via Step 0.7 keyword detection + lazy registry sync.
src/index.ts, src/projectAutoDetect.ts)main() called initializeProjectDetection(cwd) unconditionally during plugin startup → silently registered whatever directory it found instead of the actual project path.index.ts. Added explanatory comment documenting that projects must be registered explicitly via the register_project tool.explicitConfirmation: boolean = false parameter to autoDetectAndRegister() and searchWithAutoRegister() — both now block registration when flag is not set to true.initializeProjectDetection() marked as deprecated; no longer calls any registration logic.src/tools/fileSystemTools.ts, src/security.ts)max_depth parameter (default: 10, range: 1–50) to both tools with depth enforcement in walkDirectory/walkDir — prevents infinite recursion into nested directories.MAX_LINES_PER_FILE = 5000 limit inside file processing loops — prevents hanging on large files.isSafeRegex(): Added quantifier count check (>5 returns false) and consecutive quantified character class detection ([[^]]+]+[+*]) to catch additional ReDoS patterns.src/promptPreprocessor.ts, src/tools/contextManagementTools.ts) — added 2026-08-17 (v1.9.8+)search_projects results and a clarification loop.promptPreprocessor.ts): detectProjectKeyword() reads project_registry.json, fuzzy-matches message words against registered projects (hyphen↔underscore normalization), and injects a confirmation prompt before falling through to directory-path detection or RAG.contextManagementTools.ts): _syncFromSessionMemory() scans .ai_toolbox_memory.msgpack for project_path fields and auto-registers missing projects — called lazily inside search_projects / get_project_info, so no startup overhead.register_project tool call with confirmed path — no accidental registration of wrong/stale paths.max_depth and MAX_LINES_PER_FILE=5000 prevent infinite recursion and large-file hangs in grep_files/find_replace_all.search_projects/get_project_info without manual re-registration.register_project (confirmed path) remains the primary registration method; auto-sync is additive.Deadline-based hard limits for grep_files (escape-aware alternation splitting, partial results with aborted flag), mid-loop per-tool token deltas so thresholds fire inside long tool loops, and a live | chat used ≈ N tok field in [AutoTracker] [DELTA] lines.
src/tools/fileSystemTools.ts): escape-aware top-level alternation splitting + real deadline-based hard stops on the sync regex loop. New limits: GREP_SCAN_DEADLINE_MS=15000, MAX_LINE_CHARS_REGEX_MODE=20000 (long lines skipped in regex mode), PER_REGEX_TIMEOUT_MS=500 (abandon-and-continue per candidate), single-file backstop via Promise.race at deadline+5 s; over-cap files reported in skipped_files.src/tokenStatsManager.ts + 4 further source files): every tool result is measured into a running per-turn delta — threshold/compression decisions now evaluate history count + deltas instead of waiting for the next full count.[AutoTracker] [DELTA] lines append | chat used ≈ N tok, where N = turn-start TokenCheck baseline + mid-loop estimate (nested semantics: tool delta ⊆ turn total ⊆ chat used; field omitted when the ContextGuard recount fails).[TokenCheck] log values rounded via Math.round; en-US locale pins for model-facing strings.grep_files can no longer block indefinitely — worst case is deadline + 5 s with partial results flagged aborted: true.Bounded every web/RAG allocation path against plugin-host heap exhaustion and terminated the vector-RAG chunking loop that could spin forever on poison-length documents. Version stays at v1.9.10 — no bump.
rag_web_content registration removed (src/tools/webResearchTools.ts): keyword-based placeholder implementation deleted — tool now served exclusively by the real-RAG version in vectorRagTools.ts; LM Studio shows exactly one entry (dedup invariant: 1× per dist bundle).src/tools/fileSystemTools.ts): line-cap skip messages downgraded console.warn → console.log ([INFO], not [ERROR] in dev logs — already reported via skipped_files).src/performanceUtils.ts + web/HTTP tools): 250K–500K char budgets now gate fetch_web_content, all three search-engine fallbacks, the five HTTP-client body reads, and wikipedia_search; every fetchWithRetry attempt is time-bounded (30 s AbortController); new [HEAP-GUARD] watchdog logs the suspect tool name if heap usage crosses 1 GB before a crash.src/tools/vectorRagTools.ts): soft 250K char cap (oversized pages → success:true + truncated:true with usable partial chunks), HTML markup stripped via html-to-text before chunking/embedding, top-5 cosine-ranked chunks in the result payload.src/tools/vectorRagTools.ts): chunkText / chunkDocxText / chunkPdfText enforce strict forward progress (startIndex = Math.max(endIndex, startIndex + 1)) — eliminates the deterministic V8 OOM loop where certain word-count remainders stalled the window start at a fixed point near end-of-text.tests/vectorRagTools.ragWebContent.test.ts; shared-mock isolation reset in tests/webResearchTools.test.ts (beforeEach) closed the last order-dependent failure — full Jest suite green (user-verified 2026-08-25).rag_web_content tool entry in LM Studio's UI; deterministic dispatch to the real-RAG implementation.| Package | Version | Purpose |
|---|---|---|
@lmstudio/sdk | ^1.5.0 | Core SDK for LM Studio plugin development |
@dqbd/tiktoken | ^1.0.22 | Accurate token counting for ContextGuard |
puppeteer | ^24.0.0 | Browser automation |
isomorphic-git | ^1.38.6 | Pure JS Git operations (migrated from simple-git in v1.5.25) |
sharp | ^0.33.5 | Image processing |
tesseract.js | ^7.0.0 | OCR engine |
pdf-parse | ^1.1.1 | PDF document parsing |
mammoth | ^1.6.0 | DOCX document parsing |
xlsx | ^0.18.5 | XLS/XLSX spreadsheet parsing |
archiver | ^8.0.0 | ZIP archive creation |
unzipper | ^0.12.3 | ZIP extraction |
zod | ^3.25.0 | Runtime type validation |
MIT License. See LICENSE for details.