@quilltap/plugin-utils 1.2.4 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [1.2.5] - 2026-01-25
+
+### Fixed
+
+- **Environment Variable Typo**
+  - Fixed spelling of environment variable from QUIL-T-T-AP to QUIL-L-T-AP (correct: `QUILLTAP_LOG_LEVEL`)
+- **Unused Variable Cleanup**
+  - Removed unused `finalFinishReason` variable in OpenAI-compatible provider streaming
+  - Removed unused `enableLogging` functionality in roleplay template builder (option retained in API for future use)
+
 ## [1.2.4] - 2026-01-21
 
 ### Fixed

package/dist/index.d.mts

@@ -4,6 +4,50 @@ export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFact
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.mjs';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.mjs';
 
+/**
+ * Built-in tool names for Quilltap
+ *
+ * These are the tool names used by Quilltap's built-in tools.
+ * Plugins that provide dynamic tools (like MCP connectors) should use
+ * this list for collision detection to avoid shadowing built-in functionality.
+ *
+ * @module @quilltap/plugin-utils/builtin-tools
+ */
+/**
+ * Names of all built-in Quilltap tools
+ *
+ * This set contains the function names of tools that are built into Quilltap:
+ * - `generate_image` - AI image generation
+ * - `search_memories` - Search character/chat memories
+ * - `search_web` - Web search (when enabled)
+ * - `project_info` - Get project metadata
+ * - `file_management` - Read/write project files
+ * - `request_full_context` - Request full context reload (context compression)
+ */
+declare const BUILTIN_TOOL_NAMES: Set<string>;
+/**
+ * Get the set of built-in tool names
+ *
+ * Use this function to get the current list of reserved tool names
+ * when implementing collision detection in plugins that provide
+ * dynamic tools (e.g., MCP server connectors, external tool bridges).
+ *
+ * @returns Set of tool names that are reserved by Quilltap's built-in tools
+ *
+ * @example
+ * ```typescript
+ * import { getBuiltinToolNames } from '@quilltap/plugin-utils';
+ *
+ * // When generating tool names from external sources:
+ * const builtinNames = getBuiltinToolNames();
+ * if (builtinNames.has(proposedToolName)) {
+ *   // Rename or prefix the tool to avoid collision
+ *   proposedToolName = `external_${proposedToolName}`;
+ * }
+ * ```
+ */
+declare function getBuiltinToolNames(): Set<string>;
+
 /**
  * @quilltap/plugin-utils
  *
@@ -24,6 +68,6 @@ export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions,
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.2.0";
+declare const PLUGIN_UTILS_VERSION = "1.3.0";
 
-export { PLUGIN_UTILS_VERSION };
+export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, getBuiltinToolNames };

package/dist/index.d.ts

@@ -4,6 +4,50 @@ export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFact
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.js';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.js';
 
+/**
+ * Built-in tool names for Quilltap
+ *
+ * These are the tool names used by Quilltap's built-in tools.
+ * Plugins that provide dynamic tools (like MCP connectors) should use
+ * this list for collision detection to avoid shadowing built-in functionality.
+ *
+ * @module @quilltap/plugin-utils/builtin-tools
+ */
+/**
+ * Names of all built-in Quilltap tools
+ *
+ * This set contains the function names of tools that are built into Quilltap:
+ * - `generate_image` - AI image generation
+ * - `search_memories` - Search character/chat memories
+ * - `search_web` - Web search (when enabled)
+ * - `project_info` - Get project metadata
+ * - `file_management` - Read/write project files
+ * - `request_full_context` - Request full context reload (context compression)
+ */
+declare const BUILTIN_TOOL_NAMES: Set<string>;
+/**
+ * Get the set of built-in tool names
+ *
+ * Use this function to get the current list of reserved tool names
+ * when implementing collision detection in plugins that provide
+ * dynamic tools (e.g., MCP server connectors, external tool bridges).
+ *
+ * @returns Set of tool names that are reserved by Quilltap's built-in tools
+ *
+ * @example
+ * ```typescript
+ * import { getBuiltinToolNames } from '@quilltap/plugin-utils';
+ *
+ * // When generating tool names from external sources:
+ * const builtinNames = getBuiltinToolNames();
+ * if (builtinNames.has(proposedToolName)) {
+ *   // Rename or prefix the tool to avoid collision
+ *   proposedToolName = `external_${proposedToolName}`;
+ * }
+ * ```
+ */
+declare function getBuiltinToolNames(): Set<string>;
+
 /**
  * @quilltap/plugin-utils
  *
@@ -24,6 +68,6 @@ export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions,
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.2.0";
+declare const PLUGIN_UTILS_VERSION = "1.3.0";
 
-export { PLUGIN_UTILS_VERSION };
+export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, getBuiltinToolNames };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BUILTIN_TOOL_NAMES: () => BUILTIN_TOOL_NAMES,
   OpenAICompatibleProvider: () => OpenAICompatibleProvider,
   PLUGIN_UTILS_VERSION: () => PLUGIN_UTILS_VERSION,
   __clearCoreLoggerFactory: () => __clearCoreLoggerFactory,
@@ -49,6 +50,7 @@ __export(src_exports, {
   createRoleplayTemplatePlugin: () => createRoleplayTemplatePlugin,
   createSingleTemplatePlugin: () => createSingleTemplatePlugin,
   detectToolCallFormat: () => detectToolCallFormat,
+  getBuiltinToolNames: () => getBuiltinToolNames,
   getLogLevelFromEnv: () => getLogLevelFromEnv,
   hasCoreLogger: () => hasCoreLogger,
   hasToolCalls: () => hasToolCalls,
@@ -361,7 +363,7 @@ function createPluginLogger(pluginName, minLevel = "debug") {
 }
 function getLogLevelFromEnv() {
   if (typeof process !== "undefined" && process.env) {
-    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;
+    const envLevel = process.env.LOG_LEVEL || process.env.QUILLTAP_LOG_LEVEL;
     if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
       return envLevel;
     }
@@ -401,10 +403,6 @@ var OpenAICompatibleProvider = class {
       this.attachmentErrorMessage = config.attachmentErrorMessage ?? "OpenAI-compatible provider file attachment support varies by implementation (not yet implemented)";
     }
     this.logger = createPluginLogger(`${this.providerName}Provider`);
-    this.logger.debug(`${this.providerName} provider instantiated`, {
-      context: `${this.providerName}Provider.constructor`,
-      baseUrl: this.baseUrl
-    });
   }
   /**
    * Collects attachment failures for messages with attachments.
@@ -451,11 +449,6 @@ var OpenAICompatibleProvider = class {
    * @returns Complete LLM response with content and usage statistics
    */
   async sendMessage(params, apiKey) {
-    this.logger.debug(`${this.providerName} sendMessage called`, {
-      context: `${this.providerName}Provider.sendMessage`,
-      model: params.model,
-      baseUrl: this.baseUrl
-    });
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
     const client = new import_openai.default({
@@ -476,12 +469,6 @@ var OpenAICompatibleProvider = class {
         stop: params.stop
       });
       const choice = response.choices[0];
-      this.logger.debug(`Received ${this.providerName} response`, {
-        context: `${this.providerName}Provider.sendMessage`,
-        finishReason: choice.finish_reason,
-        promptTokens: response.usage?.prompt_tokens,
-        completionTokens: response.usage?.completion_tokens
-      });
       return {
         content: choice.message.content ?? "",
         finishReason: choice.finish_reason,
@@ -510,11 +497,6 @@ var OpenAICompatibleProvider = class {
    * @yields Stream chunks with content and final usage statistics
    */
   async *streamMessage(params, apiKey) {
-    this.logger.debug(`${this.providerName} streamMessage called`, {
-      context: `${this.providerName}Provider.streamMessage`,
-      model: params.model,
-      baseUrl: this.baseUrl
-    });
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
     const client = new import_openai.default({
@@ -537,26 +519,16 @@ var OpenAICompatibleProvider = class {
       });
       let chunkCount = 0;
       let accumulatedUsage = null;
-      let finalFinishReason = null;
       for await (const chunk of stream) {
         chunkCount++;
         const content = chunk.choices[0]?.delta?.content;
-        const finishReason = chunk.choices[0]?.finish_reason;
         const hasUsage = chunk.usage;
-        if (finishReason) {
-          finalFinishReason = finishReason;
-        }
         if (hasUsage) {
           accumulatedUsage = {
             prompt_tokens: chunk.usage?.prompt_tokens,
             completion_tokens: chunk.usage?.completion_tokens,
             total_tokens: chunk.usage?.total_tokens
           };
-          this.logger.debug("Received usage data in stream", {
-            context: `${this.providerName}Provider.streamMessage`,
-            promptTokens: chunk.usage?.prompt_tokens,
-            completionTokens: chunk.usage?.completion_tokens
-          });
         }
         if (content) {
           yield {
@@ -565,14 +537,6 @@ var OpenAICompatibleProvider = class {
           };
         }
       }
-      this.logger.debug("Stream completed", {
-        context: `${this.providerName}Provider.streamMessage`,
-        finishReason: finalFinishReason,
-        chunks: chunkCount,
-        promptTokens: accumulatedUsage?.prompt_tokens,
-        completionTokens: accumulatedUsage?.completion_tokens,
-        hasUsage: !!accumulatedUsage
-      });
       yield {
         content: "",
         done: true,
@@ -599,10 +563,6 @@ var OpenAICompatibleProvider = class {
    * @returns true if the API key is valid, false otherwise
    */
   async validateApiKey(apiKey) {
-    this.logger.debug(`Validating ${this.providerName} API connection`, {
-      context: `${this.providerName}Provider.validateApiKey`,
-      baseUrl: this.baseUrl
-    });
     if (this.requireApiKey && !apiKey) {
       return false;
     }
@@ -612,9 +572,6 @@ var OpenAICompatibleProvider = class {
         baseURL: this.baseUrl
       });
       await client.models.list();
-      this.logger.debug(`${this.providerName} API validation successful`, {
-        context: `${this.providerName}Provider.validateApiKey`
-      });
       return true;
     } catch (error) {
       this.logger.error(
@@ -632,10 +589,6 @@ var OpenAICompatibleProvider = class {
    * @returns Sorted array of model IDs, or empty array on failure
    */
   async getAvailableModels(apiKey) {
-    this.logger.debug(`Fetching ${this.providerName} models`, {
-      context: `${this.providerName}Provider.getAvailableModels`,
-      baseUrl: this.baseUrl
-    });
     if (this.requireApiKey && !apiKey) {
       this.logger.error(`${this.providerName} provider requires an API key to fetch models`, {
         context: `${this.providerName}Provider.getAvailableModels`
@@ -649,10 +602,6 @@ var OpenAICompatibleProvider = class {
       });
       const models = await client.models.list();
       const modelList = models.data.map((m) => m.id).sort();
-      this.logger.debug(`Retrieved ${this.providerName} models`, {
-        context: `${this.providerName}Provider.getAvailableModels`,
-        modelCount: modelList.length
-      });
       return modelList;
     } catch (error) {
       this.logger.error(
@@ -676,7 +625,7 @@ var OpenAICompatibleProvider = class {
 
 // src/roleplay-templates/builder.ts
 function createRoleplayTemplatePlugin(options) {
-  const { metadata, templates, initialize, enableLogging = false } = options;
+  const { metadata, templates, initialize, enableLogging: _enableLogging = false } = options;
   const templateArray = Array.isArray(templates) ? templates : [templates];
   if (templateArray.length === 0) {
     throw new Error("At least one template is required");
@@ -699,21 +648,9 @@ function createRoleplayTemplatePlugin(options) {
     },
     templates: templateArray
   };
-  if (initialize || enableLogging) {
+  if (initialize) {
     plugin.initialize = async () => {
-      if (enableLogging) {
-        const logger = createPluginLogger(metadata.templateId);
-        logger.debug("Roleplay template plugin loaded", {
-          context: "init",
-          templateId: metadata.templateId,
-          displayName: metadata.displayName,
-          templateCount: templateArray.length,
-          templateNames: templateArray.map((t) => t.name)
-        });
-      }
-      if (initialize) {
-        await initialize();
-      }
+      await initialize();
     };
   }
   return plugin;
@@ -796,10 +733,24 @@ function validateRoleplayTemplatePlugin(plugin) {
   return true;
 }
 
+// src/builtin-tools.ts
+var BUILTIN_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "generate_image",
+  "search_memories",
+  "search_web",
+  "project_info",
+  "file_management",
+  "request_full_context"
+]);
+function getBuiltinToolNames() {
+  return new Set(BUILTIN_TOOL_NAMES);
+}
+
 // src/index.ts
-var PLUGIN_UTILS_VERSION = "1.2.0";
+var PLUGIN_UTILS_VERSION = "1.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_TOOL_NAMES,
   OpenAICompatibleProvider,
   PLUGIN_UTILS_VERSION,
   __clearCoreLoggerFactory,
@@ -819,6 +770,7 @@ var PLUGIN_UTILS_VERSION = "1.2.0";
   createRoleplayTemplatePlugin,
   createSingleTemplatePlugin,
   detectToolCallFormat,
+  getBuiltinToolNames,
   getLogLevelFromEnv,
   hasCoreLogger,
   hasToolCalls,