Forked from crunch3r/ai-toolbox
Forked from crunch3r/ai-toolbox
src / index.ts
src / index.ts
/**
* AI Toolbox Plugin - Entry Point
* Main function exported for LM Studio plugin system
*
* ⚠️ LLM OPERATING INSTRUCTIONS (permanent — embedded in source code):
* These rules apply to ALL future sessions and all users. They are not optional preferences;
* they are hard constraints enforced by this file's structure and comments. Any LLM reading
* this file MUST follow them:
*
* 1. VERSION BUMP PROCEDURE (v1.9.8+)
* When the user asks to bump version or says "npm build shows X.X.X" (wrong version):
* a) Update package.json `version` field
* b) Update manifest.json `version` field (this is what LM Studio UI displays)
* c) Add new entry at TOP of CHANGELOG.md with date and description
* d) Update ALL documentation files: README.md, DOCUMENTATION.md, ARCHITECTURE.md, TOOLS_REFERENCE.md
* → use find_replace_all(pattern="v1.9.X", replacement="v1.9.Y") for bulk updates
* e) DO NOT skip any file — partial bumps leave inconsistent state in LM Studio UI
* Trigger: Only when user EXPLICITLY requests version bump OR reports wrong version in UI.
* Otherwise: Skip version bumps entirely (out of scope for debugging/performance sessions).
*
* 2. PROJECT REGISTRATION (v1.9.8+) — CRITICAL SAFETY RULE
* NEVER auto-register a project on startup or during search. The following is FORBIDDEN:
* - No calls to initializeProjectDetection() from main() or any startup path
* - No calls to autoDetectAndRegister() without explicitConfirmation=true
* - No calls to searchWithAutoRegister() without explicitConfirmation=true
* Correct flow when user says "let's work on <project>":
* a) promptPreprocessor.ts detects project keywords and checks registered projects
* b) If found → injects confirmation prompt asking to switch working directory
* c) User confirms → plugin switches context; if not registered, asks for path
* d) User provides path → call manage_projects(action="register") with that confirmed path (register_project remains a deprecated alias, 12.09)
* The explicitConfirmation boolean gate in projectAutoDetect.ts enforces this at runtime.
*
* 3. NO PERSISTENT MEMORY AS SUBSTITUTE FOR CODE FIXES
* Persistent memory (save_memory) only affects THIS LLM session preferences — it does NOT:
* - Change plugin behavior for other users/computers/instances
* - Propagate to future installations of this plugin
* - Replace actual code changes that are permanent and universal
* Always prefer source code fixes over persistent memory notes. Code changes are real;
* persistent memory is ephemeral LLM-side convenience at best.
*
* 4. SCOPE DISCIPLINE
* Stay strictly within debugging/performance optimization scope unless user explicitly requests:
* - New features (explicit "add feature X" request)
* - Architectural rewrites (explicit "refactor architecture" request)
* - Documentation updates (explicit "update docs" request)
* - Release management (explicit "bump version / release" request)
* If multiple valid approaches exist, present them with trade-offs rather than defaulting to one.
*/
import { type PluginContext } from '@lmstudio/sdk';
import { toolsProvider } from './toolsProvider';
import { buildConfigSchematics, configSchematics } from './config';
// UNIFIED LANGUAGE v2 step 5 (27.10): boot-time UI-label bake — panel labels follow the resolved language chain
// (persisted concrete pick → LM Studio host preference → OS locale first tag → English) instead of EN literals only.
import { getUiLabels, readPersistedUiLanguageCode, resolvePanelUiLanguage } from './uiLabelBake'; // persistConcretePick lives in promptPreprocessor (per-turn sync — the only layer with config access)
import { preprocess, setContextGuard } from './promptPreprocessor';
import { ContextGuard } from './contextGuard';
import { TokenStatsManager } from './tokenStatsManager';
import { cleanupBrowserSession } from './tools/browserAutomationTools';
import { autoTracker } from './autoTracker';
import { restoreLastActiveProjectCwd } from './workingDir.js';
// Export for external use (e.g., in generators or other plugins)
export { TokenStatsManager };
// ✅ FIX: Use structured logging instead of console.log
const logger = {
info: (msg: string) => typeof process.stdout.write === 'function' && process.stdout.write(`[AI Toolbox] ${msg}\n`),
warn: (msg: string) => typeof process.stderr.write === 'function' && process.stderr.write(`[AI Toolbox WARN] ${msg}\n`),
error: (msg: string) => typeof process.stderr.write === 'function' && process.stderr.write(`[AI Toolbox ERROR] ${msg}\n`),
};
/**
* Main plugin entry point - called by LM Studio
*/
export function main(context: PluginContext) {
logger.info('Initializing...');
// ⚠️ NO AUTO-REGISTRATION ON STARTUP — projects must be registered explicitly via the manage_projects tool (action='register')
// This prevents silent registration of wrong/stale paths without user confirmation.
// Restore last-active project CWD if persisted state is missing/invalid (e.g., after a plugin reinstall).
// NOT auto-registration — only re-applies projects already known from the registry/session index.
try {
const restore = restoreLastActiveProjectCwd();
if (restore.restored) logger.info(`Restored last-active project CWD: ${restore.project}`);
} catch (e) {
logger.warn(`CWD restore failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
}
// UNIFIED LANGUAGE v2 step 5 (27.10): bake the panel labels from the resolved language chain BEFORE registering
// the config schematics — persisted concrete pick → LM Studio host preference → OS locale first tag → English
// ('auto' falls through by construction and can never reach a bundle). EN byte-safety: en resolution renders the
// pre-v2 literals plus the new 'auto' option only. The panel is registered ONCE at boot, so a concrete pick chosen
// mid-session takes effect on reload (the per-turn state-file sync in promptPreprocessor keeps that pick durable);
// prompt texts follow configuration immediately via step 4's per-turn wiring — by design.
try {
// Option A (02.11): global scope — settings register app-wide so toggles persist across chats and app restarts.
const bakedLang = resolvePanelUiLanguage(readPersistedUiLanguageCode());
context.withGlobalConfigSchematics(buildConfigSchematics(getUiLabels(bakedLang)));
logger.info(`[UL-v2] Panel UI labels baked for '${bakedLang}' (chain: persisted pick → host locale → OS first tag → en)`);
} catch (e) {
// i18n must never block plugin boot — fall back to the pre-v2 EN-literal schematics.
logger.warn(`[UL-v2] UI-label bake failed (falling back to EN literals): ${e instanceof Error ? e.message : String(e)}`);
context.withGlobalConfigSchematics(configSchematics); // Option A (02.11): global scope — fallback keeps one registration mode with the primary path above
}
// Initialize ContextGuard with default settings
const contextGuard = new ContextGuard({
tokenLimit: 30000, // 📊 Fallback effective window (07.10) — used ONLY when the active model does not report its
// context window; dynamically overridden by SDK model info at runtime. Was 262144 while the menu
// carried an absolute limit re-seeded each turn; with the percent-only setting this constant IS
// the unreporting-model default (preserves the former 30k/27k trigger at defaults).
compressionPercent: 90, // Compression trigger as % of tokenLimit — mirrors DEFAULT_CONFIG.contextGuardCompressionPercent
smartReading: true, // Enables keyword-based file reading
summaryModel: '', // Empty = use current chat model for summarization
terminalFilterEnabled: true, // Truncates long terminal outputs
terminalFilterLength: 2000, // Max chars before truncation
});
// 🔹 Coordinate ContextGuard + AutoTracker: when compression happens, reset AutoTracker state
contextGuard.onCompression = () => {
autoTracker.onContextCompressed();
};
// Connect ContextGuard to the prompt preprocessor
setContextGuard(contextGuard);
// Register the prompt preprocessor for Document RAG / Chat with Files
context.withPromptPreprocessor(preprocess);
// Note: LM Studio SDK v1.5.0 doesn't expose getConfig() on PluginContext.
// Configuration is handled automatically by the SDK's config system.
// The toolsProvider will use default settings until UI toggles are applied.
// Register the tools provider function
context.withToolsProvider(toolsProvider);
// Handle plugin unload - cleanup browser session to prevent orphaned processes
if (typeof process.on === 'function') {
process.on('SIGTERM', async () => {
await cleanupBrowserSession();
});
process.on('SIGINT', async () => {
await cleanupBrowserSession();
});
}
logger.info('Initialized successfully!');
}
/**
* AI Toolbox Plugin - Entry Point
* Main function exported for LM Studio plugin system
*
* ⚠️ LLM OPERATING INSTRUCTIONS (permanent — embedded in source code):
* These rules apply to ALL future sessions and all users. They are not optional preferences;
* they are hard constraints enforced by this file's structure and comments. Any LLM reading
* this file MUST follow them:
*
* 1. VERSION BUMP PROCEDURE (v1.9.8+)
* When the user asks to bump version or says "npm build shows X.X.X" (wrong version):
* a) Update package.json `version` field
* b) Update manifest.json `version` field (this is what LM Studio UI displays)
* c) Add new entry at TOP of CHANGELOG.md with date and description
* d) Update ALL documentation files: README.md, DOCUMENTATION.md, ARCHITECTURE.md, TOOLS_REFERENCE.md
* → use find_replace_all(pattern="v1.9.X", replacement="v1.9.Y") for bulk updates
* e) DO NOT skip any file — partial bumps leave inconsistent state in LM Studio UI
* Trigger: Only when user EXPLICITLY requests version bump OR reports wrong version in UI.
* Otherwise: Skip version bumps entirely (out of scope for debugging/performance sessions).
*
* 2. PROJECT REGISTRATION (v1.9.8+) — CRITICAL SAFETY RULE
* NEVER auto-register a project on startup or during search. The following is FORBIDDEN:
* - No calls to initializeProjectDetection() from main() or any startup path
* - No calls to autoDetectAndRegister() without explicitConfirmation=true
* - No calls to searchWithAutoRegister() without explicitConfirmation=true
* Correct flow when user says "let's work on <project>":
* a) promptPreprocessor.ts detects project keywords and checks registered projects
* b) If found → injects confirmation prompt asking to switch working directory
* c) User confirms → plugin switches context; if not registered, asks for path
* d) User provides path → call manage_projects(action="register") with that confirmed path (register_project remains a deprecated alias, 12.09)
* The explicitConfirmation boolean gate in projectAutoDetect.ts enforces this at runtime.
*
* 3. NO PERSISTENT MEMORY AS SUBSTITUTE FOR CODE FIXES
* Persistent memory (save_memory) only affects THIS LLM session preferences — it does NOT:
* - Change plugin behavior for other users/computers/instances
* - Propagate to future installations of this plugin
* - Replace actual code changes that are permanent and universal
* Always prefer source code fixes over persistent memory notes. Code changes are real;
* persistent memory is ephemeral LLM-side convenience at best.
*
* 4. SCOPE DISCIPLINE
* Stay strictly within debugging/performance optimization scope unless user explicitly requests:
* - New features (explicit "add feature X" request)
* - Architectural rewrites (explicit "refactor architecture" request)
* - Documentation updates (explicit "update docs" request)
* - Release management (explicit "bump version / release" request)
* If multiple valid approaches exist, present them with trade-offs rather than defaulting to one.
*/
import { type PluginContext } from '@lmstudio/sdk';
import { toolsProvider } from './toolsProvider';
import { buildConfigSchematics, configSchematics } from './config';
// UNIFIED LANGUAGE v2 step 5 (27.10): boot-time UI-label bake — panel labels follow the resolved language chain
// (persisted concrete pick → LM Studio host preference → OS locale first tag → English) instead of EN literals only.
import { getUiLabels, readPersistedUiLanguageCode, resolvePanelUiLanguage } from './uiLabelBake'; // persistConcretePick lives in promptPreprocessor (per-turn sync — the only layer with config access)
import { preprocess, setContextGuard } from './promptPreprocessor';
import { ContextGuard } from './contextGuard';
import { TokenStatsManager } from './tokenStatsManager';
import { cleanupBrowserSession } from './tools/browserAutomationTools';
import { autoTracker } from './autoTracker';
import { restoreLastActiveProjectCwd } from './workingDir.js';
// Export for external use (e.g., in generators or other plugins)
export { TokenStatsManager };
// ✅ FIX: Use structured logging instead of console.log
const logger = {
info: (msg: string) => typeof process.stdout.write === 'function' && process.stdout.write(`[AI Toolbox] ${msg}\n`),
warn: (msg: string) => typeof process.stderr.write === 'function' && process.stderr.write(`[AI Toolbox WARN] ${msg}\n`),
error: (msg: string) => typeof process.stderr.write === 'function' && process.stderr.write(`[AI Toolbox ERROR] ${msg}\n`),
};
/**
* Main plugin entry point - called by LM Studio
*/
export function main(context: PluginContext) {
logger.info('Initializing...');
// ⚠️ NO AUTO-REGISTRATION ON STARTUP — projects must be registered explicitly via the manage_projects tool (action='register')
// This prevents silent registration of wrong/stale paths without user confirmation.
// Restore last-active project CWD if persisted state is missing/invalid (e.g., after a plugin reinstall).
// NOT auto-registration — only re-applies projects already known from the registry/session index.
try {
const restore = restoreLastActiveProjectCwd();
if (restore.restored) logger.info(`Restored last-active project CWD: ${restore.project}`);
} catch (e) {
logger.warn(`CWD restore failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`);
}
// UNIFIED LANGUAGE v2 step 5 (27.10): bake the panel labels from the resolved language chain BEFORE registering
// the config schematics — persisted concrete pick → LM Studio host preference → OS locale first tag → English
// ('auto' falls through by construction and can never reach a bundle). EN byte-safety: en resolution renders the
// pre-v2 literals plus the new 'auto' option only. The panel is registered ONCE at boot, so a concrete pick chosen
// mid-session takes effect on reload (the per-turn state-file sync in promptPreprocessor keeps that pick durable);
// prompt texts follow configuration immediately via step 4's per-turn wiring — by design.
try {
// Option A (02.11): global scope — settings register app-wide so toggles persist across chats and app restarts.
const bakedLang = resolvePanelUiLanguage(readPersistedUiLanguageCode());
context.withGlobalConfigSchematics(buildConfigSchematics(getUiLabels(bakedLang)));
logger.info(`[UL-v2] Panel UI labels baked for '${bakedLang}' (chain: persisted pick → host locale → OS first tag → en)`);
} catch (e) {
// i18n must never block plugin boot — fall back to the pre-v2 EN-literal schematics.
logger.warn(`[UL-v2] UI-label bake failed (falling back to EN literals): ${e instanceof Error ? e.message : String(e)}`);
context.withGlobalConfigSchematics(configSchematics); // Option A (02.11): global scope — fallback keeps one registration mode with the primary path above
}
// Initialize ContextGuard with default settings
const contextGuard = new ContextGuard({
tokenLimit: 30000, // 📊 Fallback effective window (07.10) — used ONLY when the active model does not report its
// context window; dynamically overridden by SDK model info at runtime. Was 262144 while the menu
// carried an absolute limit re-seeded each turn; with the percent-only setting this constant IS
// the unreporting-model default (preserves the former 30k/27k trigger at defaults).
compressionPercent: 90, // Compression trigger as % of tokenLimit — mirrors DEFAULT_CONFIG.contextGuardCompressionPercent
smartReading: true, // Enables keyword-based file reading
summaryModel: '', // Empty = use current chat model for summarization
terminalFilterEnabled: true, // Truncates long terminal outputs
terminalFilterLength: 2000, // Max chars before truncation
});
// 🔹 Coordinate ContextGuard + AutoTracker: when compression happens, reset AutoTracker state
contextGuard.onCompression = () => {
autoTracker.onContextCompressed();
};
// Connect ContextGuard to the prompt preprocessor
setContextGuard(contextGuard);
// Register the prompt preprocessor for Document RAG / Chat with Files
context.withPromptPreprocessor(preprocess);
// Note: LM Studio SDK v1.5.0 doesn't expose getConfig() on PluginContext.
// Configuration is handled automatically by the SDK's config system.
// The toolsProvider will use default settings until UI toggles are applied.
// Register the tools provider function
context.withToolsProvider(toolsProvider);
// Handle plugin unload - cleanup browser session to prevent orphaned processes
if (typeof process.on === 'function') {
process.on('SIGTERM', async () => {
await cleanupBrowserSession();
});
process.on('SIGINT', async () => {
await cleanupBrowserSession();
});
}
logger.info('Initialized successfully!');
}