ai-toolbox
Public
Forked from crunch3r/ai-toolbox
Forked from crunch3r/ai-toolbox
Date: 2026-08-01
Version: v1.8.7 (Token Counting Calibration, Config Exports, Drift Detection & Version Bump)
Status: ✅ Complete
The following tools ONLY accept HTTP/HTTPS URLs and will FAIL with "Only HTTP and HTTPS URLs are allowed" if given file:// paths:
searxng_batch_fetch(urls) — Batch fetch multiple REMOTE pages (HTTP/HTTPS only!)fetch_web_content(url) — Fetch single remote webpage (HTTP/HTTPS only!)searxng_search(query) — Web search ONLY, not local file access!read_file(file_name="CHANGELOG.md") — Read single local filefind_files(pattern=".md", max_depth=5) — Find files by name pattern, then read each result❌ WRONG (will fail): searxng_batch_fetch(urls=["file:///C:/path/file.md"])
✅ CORRECT: read_file(file_name="CHANGELOG.md", max_length=5000) for local files
See CRITICAL_TOOL_USAGE_RULES.md in project root for complete reference.
Resolved critical token counting inaccuracy and missing checkpoint prompt injection issues.
Architectural overhaul of tool registration system.
TOOL_REGISTRIES) containing 20 entriesconfig, stateManager, and at definition time via arrow functionsFixed critical performance issue where grep_files searched ALL directories.
Resolved critical token undercounting bug.
ContextGuard.countTokens() now properly extracts text from arrays of content blocks.getText() method or .text property before JSON serialization@typescript-eslint/no-base-to-string error with explicit type checksThe priority system (maxToolsInSchema, tier-based filtering, toolPriorityOverrides) was removed in v1.6.4 because:
toolsSchemaMinifier.ts)Replacement: toolsSchemaMinifier.ts handles grammar parser compatibility via description truncation (~150 chars) and constraint capping. No manual limits needed.
The gateway pattern (src/tools/gatewayTools.ts) was introduced in v1.6.0 but abandoned in favor of direct SDK registration (v1.8.0+).
The following corrections reflect the current v1.8.2 implementation:
| Category | Previous Count | Corrected Count | Changes |
|---|---|---|---|
| File System Tools | 21 → 22 | 22 tools | Added fuzzy_find_local_files (previously counted separately) |
| Web Research Tools | 4 | 4 tools | No change |
| Browser Automation Tools | 5 | 5 tools | No change |
| Git & GitHub Tools | 13 → 15 | 15 tools | Added git_stash, git_blame (v1.5.23) |
| Database Tools | 1 | 1 tool | No change |
| Document Parsing | 1 | 1 tool | No change |
| Background Commands | 3 | 3 tools | No change |
| Execution Tools | 4 → 5 | 5 tools |
The isSafeRegex() function in src/security.ts performs precise pattern analysis:
(.+)+, (a*)*), alternating groups with quantifiers (((a|b)+)+)All dangerous tool categories are disabled by default:
| Category | Default State |
|---|---|
browserAutomation | false |
gitOperations | false |
databaseQueries | false |
executionJavaScript / executionPython | Enabled (sandboxed) |
executionTerminal / executionShell | false |
Debounced State Saves: _queueSave() in stateManager.ts coalesces rapid set/delete/clear calls within a 500ms window → single batched disk write instead of N individual writes (~90% I/O reduction during bulk ops).
| Cache | TTL / Window | Max Entries | Purpose |
|---|---|---|---|
State Key Cache (_keysCache) | 1s TTL + invalidate on mutation | N/A | O(1) getAllKeys() — eliminates disk reload during auto-tracker checks |
Size Estimation Cache (sizeValueCache) | Per-object, memoized JSON.stringify() | Unbounded | O(1) vs. O(n serialization) for repeated complex state values |
Project Path Cache (_projectPathCache) | 5s TTL with staleness check | N/A | Eliminates duplicate fs.stat() on getProjectMemoryFilePath() |
| Fuzzy Search Cache | 60s TTL + LRU eviction via Map order | 100 entries | File name similarity results; frequently queried paths stay cached |
AI_TOOLBOX_DEBUG unset): ~80% fewer console.warn() calls — threshold near-misses (~95%), state transitions, and buffer operations are suppressed.$env:AI_TOOLBOX_DEBUG="true" on Windows / export AI_TOOLBOX_DEBUG=true on Linux/macOS): Full diagnostic output for all auto-tracker checks, context guard token counting, compression steps, and file read operations.config.ts Zod schema exactlyindex.ts implementation| File | Changes Made |
|---|---|
README.md | Up-to-date (v1.8.7 release history, ~97 tools) |
ARCHITECTURE.md | Gateway Pattern marked as ABANDONED; tool counts corrected to 20 modules |
TOOLS_REFERENCE.md | Up-to-date (~132 tools documented) |
DOCUMENTATION.md | Deprecated features clearly marked; tool count corrections applied |
CHANGELOG.md | Up-to-date (v1.8.0–v1.8.2 entries complete) |
CONTRIBUTING.md | Updated to show declarative registry pattern for adding new tools (v1.8.2+) |
SECURITY.md | Up-to-date (threat model, security controls) |
SUMMARY.md | Rebuilt with v1.8.2 status, deprecated features noted |
These documentation updates correspond to the following source code locations:
| Source File | Documentation Section | Verification Method |
|---|---|---|
src/config.ts | Configuration tables in README.md, ARCHITECTURE.md | Zod schema fields match documented settings exactly |
src/tools/*.ts (20 files) | Tool counts and descriptions in all MD files | Manual count of registered tools per category |
src/index.ts | Plugin lifecycle in ARCHITECTURE.md | Code flow matches documented initialization sequence |
src/security.ts | Security pipeline documentation | Validation functions match documented threat model |
src/toolsProvider.ts | Declarative registry pattern (v1.8.2+) | Closure-based registry with 20 entries, single for...of loop |
All changes verified with comprehensive test suite:
npx tsc --noEmit — 0 errors)npm run lint)npm run build)@/ → src/) in both tsconfig.json and docs: update documentation for v1.8.2 — declarative registry, deprecated features markednpm run testsrc/toolsProvider.ts.src/config.ts.src/security.ts and individual tool modules..content casting with LM Studio's native history API (getLength(), at(i), getText()), matching vibe-lm's approach. The previous code assumed msg.content was always accessible via property access, but SDK messages use getter methods instead — resulting in 0 character counts and inaccurate token estimates.countTokens() × 65 calibration to History Text Length × 0.24 ratio. Empirical testing confirmed that historyChars × 0.24 matches LM Studio sidebar token counts exactly (verified at ~130K tokens for 544,578 chars), whereas SDK-native counting with ×65 overestimated by ~45k tokens (~124K vs ~80K).checkpointSuffix variable in promptPreprocessor.ts that guarantees the auto-tracking threshold prompt is injected into every possible code path (directory detection, RAG disabled, no files found). Previously, the warning was silently swallowed due to early-return gates.backgroundCommandManagerany[] types, replaced with typed closures (() => Tool[])for...of iteration replaces scattered conditional blocksDEFAULT_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)Added run_tests (v1.5.23) |
| Utilities | ~29 → ~10 | ~10 tools | Refactored into dedicated modules (backup, data visualization, line operations, markdown preview) under utility config key |
| Image Processing | 4 | 4 tools | No change |
| HTTP Client | 3 | 3 tools | No change |
| Vector RAG | 3 → 4 | 4 tools | Added rag_web_content (v1.5.23) |
| Text Processing | 3 → 4 | 4 tools | Added line_operations with safety guardrails (v1.7.0) |
| Interactive UI Generation | 3 | 3 tools | No change |
| Context Management | 7 → 12 | 12 tools | Expanded to include all memory/context operations |
| AST Refactoring | N/A | 2 tools | refactor_code, unusedImports (v1.5.30+) |
| Backup Operations | N/A | 5 tools | Registered under utility toggle (v1.6.2+) |
| Data Visualization | N/A | 1 tool | generate_chart registered under utility toggle |
| Line Operations | N/A | 1 tool | With safety guardrails (v1.7.0) |
| Markdown Preview | N/A | 1 tool | Registered under utility toggle |
(a|b)+, [a-z]+, ^import\s+ are correctly acceptedgrep_files returns patternMode: 'regex' | 'literal' field indicating match modetsup.config.tsStep 1: Is this a LOCAL file or REMOTE URL?
IF LOCAL FILE (file://, C:/path/, ./relative/):
→ Use read_file(file_name) for single files
→ Use find_files(pattern) to search first, then read each result
IF REMOTE URL (http://, https://):
→ Use fetch_web_content(url) for single page
→ Use searxng_batch_fetch(urls=[...]) for multiple pages at once
→ Use searxng_search(query="...") for web search only