@quilltap/plugin-utils 1.5.4 → 1.6.1

package/dist/index.d.mts

@@ -4,6 +4,7 @@ export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFact
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.mjs';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.mjs';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.mjs';
+import 'openai';
 
 /**
  * Built-in tool names for Quilltap
@@ -51,6 +52,68 @@ declare const BUILTIN_TOOL_NAMES: Set<string>;
  */
 declare function getBuiltinToolNames(): Set<string>;
 
+/**
+ * Quilltap Version Management
+ *
+ * Provides access to the Quilltap application version for plugins.
+ * Uses the same globalThis injection pattern as the logger factory,
+ * allowing the host app to inject its version at startup.
+ *
+ * @module @quilltap/plugin-utils/version
+ */
+/**
+ * Inject the Quilltap application version into the global namespace.
+ *
+ * This should be called early in plugin initialization (alongside the
+ * logger factory injection), before any plugins are loaded. Plugins
+ * can then retrieve the version via `getQuilltapVersion()`.
+ *
+ * @param version - The Quilltap application version string (e.g., '3.3.0')
+ *
+ * @example
+ * ```typescript
+ * import { __injectQuilltapVersion } from '@quilltap/plugin-utils';
+ * import packageJson from './package.json';
+ *
+ * __injectQuilltapVersion(packageJson.version);
+ * ```
+ */
+declare function __injectQuilltapVersion(version: string): void;
+/**
+ * Clear the injected Quilltap version from the global namespace.
+ *
+ * Useful for testing or cleanup.
+ */
+declare function __clearQuilltapVersion(): void;
+/**
+ * Get the Quilltap application version.
+ *
+ * Returns the version injected by the host app, or 'unknown' if
+ * no version has been injected (e.g., running outside of Quilltap).
+ *
+ * @returns The Quilltap version string (e.g., '3.3.0') or 'unknown'
+ */
+declare function getQuilltapVersion(): string;
+/**
+ * Get the Quilltap User-Agent string for API requests.
+ *
+ * Returns a string in the format `Quilltap/{version}` suitable for
+ * use as a User-Agent header or app identifier in API calls.
+ *
+ * @returns User-Agent string (e.g., 'Quilltap/3.3.0')
+ *
+ * @example
+ * ```typescript
+ * import { getQuilltapUserAgent } from '@quilltap/plugin-utils';
+ *
+ * const client = new OpenAI({
+ *   apiKey,
+ *   defaultHeaders: { 'User-Agent': getQuilltapUserAgent() },
+ * });
+ * ```
+ */
+declare function getQuilltapUserAgent(): string;
+
 /**
  * @quilltap/plugin-utils
  *
@@ -71,6 +134,6 @@ declare function getBuiltinToolNames(): Set<string>;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.4.0";
+declare const PLUGIN_UTILS_VERSION = "1.6.1";
 
-export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, getBuiltinToolNames };
+export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFact
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.js';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.js';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.js';
+import 'openai';
 
 /**
  * Built-in tool names for Quilltap
@@ -51,6 +52,68 @@ declare const BUILTIN_TOOL_NAMES: Set<string>;
  */
 declare function getBuiltinToolNames(): Set<string>;
 
+/**
+ * Quilltap Version Management
+ *
+ * Provides access to the Quilltap application version for plugins.
+ * Uses the same globalThis injection pattern as the logger factory,
+ * allowing the host app to inject its version at startup.
+ *
+ * @module @quilltap/plugin-utils/version
+ */
+/**
+ * Inject the Quilltap application version into the global namespace.
+ *
+ * This should be called early in plugin initialization (alongside the
+ * logger factory injection), before any plugins are loaded. Plugins
+ * can then retrieve the version via `getQuilltapVersion()`.
+ *
+ * @param version - The Quilltap application version string (e.g., '3.3.0')
+ *
+ * @example
+ * ```typescript
+ * import { __injectQuilltapVersion } from '@quilltap/plugin-utils';
+ * import packageJson from './package.json';
+ *
+ * __injectQuilltapVersion(packageJson.version);
+ * ```
+ */
+declare function __injectQuilltapVersion(version: string): void;
+/**
+ * Clear the injected Quilltap version from the global namespace.
+ *
+ * Useful for testing or cleanup.
+ */
+declare function __clearQuilltapVersion(): void;
+/**
+ * Get the Quilltap application version.
+ *
+ * Returns the version injected by the host app, or 'unknown' if
+ * no version has been injected (e.g., running outside of Quilltap).
+ *
+ * @returns The Quilltap version string (e.g., '3.3.0') or 'unknown'
+ */
+declare function getQuilltapVersion(): string;
+/**
+ * Get the Quilltap User-Agent string for API requests.
+ *
+ * Returns a string in the format `Quilltap/{version}` suitable for
+ * use as a User-Agent header or app identifier in API calls.
+ *
+ * @returns User-Agent string (e.g., 'Quilltap/3.3.0')
+ *
+ * @example
+ * ```typescript
+ * import { getQuilltapUserAgent } from '@quilltap/plugin-utils';
+ *
+ * const client = new OpenAI({
+ *   apiKey,
+ *   defaultHeaders: { 'User-Agent': getQuilltapUserAgent() },
+ * });
+ * ```
+ */
+declare function getQuilltapUserAgent(): string;
+
 /**
  * @quilltap/plugin-utils
  *
@@ -71,6 +134,6 @@ declare function getBuiltinToolNames(): Set<string>;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.4.0";
+declare const PLUGIN_UTILS_VERSION = "1.6.1";
 
-export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, getBuiltinToolNames };
+export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.js

@@ -34,7 +34,9 @@ __export(src_exports, {
   OpenAICompatibleProvider: () => OpenAICompatibleProvider,
   PLUGIN_UTILS_VERSION: () => PLUGIN_UTILS_VERSION,
   __clearCoreLoggerFactory: () => __clearCoreLoggerFactory,
+  __clearQuilltapVersion: () => __clearQuilltapVersion,
   __injectCoreLoggerFactory: () => __injectCoreLoggerFactory,
+  __injectQuilltapVersion: () => __injectQuilltapVersion,
   applyDescriptionLimit: () => applyDescriptionLimit,
   convertFromAnthropicFormat: () => convertFromAnthropicFormat,
   convertFromGoogleFormat: () => convertFromGoogleFormat,
@@ -52,6 +54,8 @@ __export(src_exports, {
   detectToolCallFormat: () => detectToolCallFormat,
   getBuiltinToolNames: () => getBuiltinToolNames,
   getLogLevelFromEnv: () => getLogLevelFromEnv,
+  getQuilltapUserAgent: () => getQuilltapUserAgent,
+  getQuilltapVersion: () => getQuilltapVersion,
   hasCoreLogger: () => hasCoreLogger,
   hasToolCalls: () => hasToolCalls,
   isVMEnvironment: () => isVMEnvironment,
@@ -381,6 +385,24 @@ var import_plugin_types = require("@quilltap/plugin-types");
 
 // src/providers/openai-compatible.ts
 var import_openai = __toESM(require("openai"));
+
+// src/version.ts
+var GLOBAL_VERSION_KEY = "__quilltap_app_version";
+function __injectQuilltapVersion(version) {
+  globalThis[GLOBAL_VERSION_KEY] = version;
+}
+function __clearQuilltapVersion() {
+  globalThis[GLOBAL_VERSION_KEY] = void 0;
+}
+function getQuilltapVersion() {
+  const version = globalThis[GLOBAL_VERSION_KEY];
+  return typeof version === "string" ? version : "unknown";
+}
+function getQuilltapUserAgent() {
+  return `Quilltap/${getQuilltapVersion()}`;
+}
+
+// src/providers/openai-compatible.ts
 var OpenAICompatibleProvider = class {
   /**
    * Creates a new OpenAI-compatible provider instance.
@@ -446,6 +468,20 @@ var OpenAICompatibleProvider = class {
   getEffectiveApiKey(apiKey) {
     return this.requireApiKey ? apiKey : apiKey || "not-needed";
   }
+  /**
+   * Creates an OpenAI client configured with the provider's base URL,
+   * API key, and Quilltap User-Agent header.
+   *
+   * @param apiKey - API key for authentication
+   * @returns Configured OpenAI client instance
+   */
+  createClient(apiKey) {
+    return new import_openai.default({
+      apiKey: this.getEffectiveApiKey(apiKey),
+      baseURL: this.baseUrl,
+      defaultHeaders: { "User-Agent": getQuilltapUserAgent() }
+    });
+  }
   /**
    * Sends a message and returns the complete response.
    *
@@ -456,10 +492,7 @@ var OpenAICompatibleProvider = class {
   async sendMessage(params, apiKey) {
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
-    const client = new import_openai.default({
-      apiKey: this.getEffectiveApiKey(apiKey),
-      baseURL: this.baseUrl
-    });
+    const client = this.createClient(apiKey);
     const messages = params.messages.filter((m) => {
       if (m.role === "tool" && !m.toolCallId) return false;
       return true;
@@ -527,10 +560,7 @@ var OpenAICompatibleProvider = class {
   async *streamMessage(params, apiKey) {
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
-    const client = new import_openai.default({
-      apiKey: this.getEffectiveApiKey(apiKey),
-      baseURL: this.baseUrl
-    });
+    const client = this.createClient(apiKey);
     const messages = params.messages.filter((m) => {
       if (m.role === "tool" && !m.toolCallId) return false;
       return true;
@@ -618,10 +648,7 @@ var OpenAICompatibleProvider = class {
       return false;
     }
     try {
-      const client = new import_openai.default({
-        apiKey: this.getEffectiveApiKey(apiKey),
-        baseURL: this.baseUrl
-      });
+      const client = this.createClient(apiKey);
       await client.models.list();
       return true;
     } catch (error) {
@@ -647,10 +674,7 @@ var OpenAICompatibleProvider = class {
       return [];
     }
     try {
-      const client = new import_openai.default({
-        apiKey: this.getEffectiveApiKey(apiKey),
-        baseURL: this.baseUrl
-      });
+      const client = this.createClient(apiKey);
       const models = await client.models.list();
       const modelList = models.data.map((m) => m.id).sort();
       return modelList;
@@ -932,14 +956,16 @@ function rewriteLocalhostUrl(url) {
 }
 
 // src/index.ts
-var PLUGIN_UTILS_VERSION = "1.4.0";
+var PLUGIN_UTILS_VERSION = "1.6.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILTIN_TOOL_NAMES,
   OpenAICompatibleProvider,
   PLUGIN_UTILS_VERSION,
   __clearCoreLoggerFactory,
+  __clearQuilltapVersion,
   __injectCoreLoggerFactory,
+  __injectQuilltapVersion,
   applyDescriptionLimit,
   convertFromAnthropicFormat,
   convertFromGoogleFormat,
@@ -957,6 +983,8 @@ var PLUGIN_UTILS_VERSION = "1.4.0";
   detectToolCallFormat,
   getBuiltinToolNames,
   getLogLevelFromEnv,
+  getQuilltapUserAgent,
+  getQuilltapVersion,
   hasCoreLogger,
   hasToolCalls,
   isVMEnvironment,