@quilltap/plugin-utils 1.0.0

package/dist/logging/index.d.ts

@@ -0,0 +1,109 @@
+import { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';
+export { LogContext, LogLevel, PluginLogger, createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';
+
+/**
+ * Plugin Logger Bridge
+ *
+ * Provides a logger factory for plugins that automatically bridges
+ * to Quilltap's core logging when running inside the host application,
+ * or falls back to console logging when running standalone.
+ *
+ * @module @quilltap/plugin-utils/logging/plugin-logger
+ */
+
+/**
+ * Extended logger interface with child logger support
+ */
+interface PluginLoggerWithChild extends PluginLogger {
+    /**
+     * Create a child logger with additional context
+     * @param additionalContext Context to merge with parent context
+     * @returns A new logger with combined context
+     */
+    child(additionalContext: LogContext): PluginLoggerWithChild;
+}
+/**
+ * Type for the global Quilltap logger bridge
+ * Stored on globalThis to work across different npm package copies
+ */
+declare global {
+    var __quilltap_logger_factory: ((pluginName: string) => PluginLoggerWithChild) | undefined;
+}
+/**
+ * Inject the core logger factory from Quilltap host
+ *
+ * This is called by Quilltap core when loading plugins to bridge
+ * plugin logging into the host's logging system. Uses globalThis
+ * to ensure it works even when plugins have their own copy of
+ * plugin-utils in their node_modules.
+ *
+ * **Internal API - not for plugin use**
+ *
+ * @param factory A function that creates a child logger for a plugin
+ */
+declare function __injectCoreLoggerFactory(factory: (pluginName: string) => PluginLoggerWithChild): void;
+/**
+ * Clear the injected core logger factory
+ *
+ * Useful for testing or when unloading the plugin system.
+ *
+ * **Internal API - not for plugin use**
+ */
+declare function __clearCoreLoggerFactory(): void;
+/**
+ * Check if a core logger has been injected
+ *
+ * @returns True if running inside Quilltap with core logging available
+ */
+declare function hasCoreLogger(): boolean;
+/**
+ * Create a plugin logger that bridges to Quilltap core logging
+ *
+ * When running inside Quilltap:
+ * - Routes all logs to the core logger
+ * - Tags logs with `{ plugin: pluginName, module: 'plugin' }`
+ * - Logs appear in Quilltap's combined.log and console
+ *
+ * When running standalone:
+ * - Falls back to console logging with `[pluginName]` prefix
+ * - Respects the specified minimum log level
+ *
+ * @param pluginName - The plugin identifier (e.g., 'qtap-plugin-openai')
+ * @param minLevel - Minimum log level when running standalone (default: 'debug')
+ * @returns A logger instance
+ *
+ * @example
+ * ```typescript
+ * // In your plugin's provider.ts
+ * import { createPluginLogger } from '@quilltap/plugin-utils';
+ *
+ * const logger = createPluginLogger('qtap-plugin-my-provider');
+ *
+ * export class MyProvider implements LLMProvider {
+ *   async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {
+ *     logger.debug('Sending message', { model: params.model });
+ *
+ *     try {
+ *       const response = await this.client.chat({...});
+ *       logger.info('Received response', { tokens: response.usage?.total_tokens });
+ *       return response;
+ *     } catch (error) {
+ *       logger.error('Failed to send message', { model: params.model }, error as Error);
+ *       throw error;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function createPluginLogger(pluginName: string, minLevel?: LogLevel): PluginLoggerWithChild;
+/**
+ * Get the minimum log level from environment
+ *
+ * Checks for LOG_LEVEL or QUILTTAP_LOG_LEVEL environment variables.
+ * Useful for configuring standalone plugin logging.
+ *
+ * @returns The configured log level, or 'info' as default
+ */
+declare function getLogLevelFromEnv(): LogLevel;
+
+export { type PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger };

package/dist/logging/index.js

@@ -0,0 +1,117 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/logging/index.ts
+var logging_exports = {};
+__export(logging_exports, {
+  __clearCoreLoggerFactory: () => __clearCoreLoggerFactory,
+  __injectCoreLoggerFactory: () => __injectCoreLoggerFactory,
+  createConsoleLogger: () => import_plugin_types.createConsoleLogger,
+  createNoopLogger: () => import_plugin_types.createNoopLogger,
+  createPluginLogger: () => createPluginLogger,
+  getLogLevelFromEnv: () => getLogLevelFromEnv,
+  hasCoreLogger: () => hasCoreLogger
+});
+module.exports = __toCommonJS(logging_exports);
+
+// src/logging/plugin-logger.ts
+function getCoreLoggerFactory() {
+  return globalThis.__quilltap_logger_factory ?? null;
+}
+function __injectCoreLoggerFactory(factory) {
+  globalThis.__quilltap_logger_factory = factory;
+}
+function __clearCoreLoggerFactory() {
+  globalThis.__quilltap_logger_factory = void 0;
+}
+function hasCoreLogger() {
+  return getCoreLoggerFactory() !== null;
+}
+function createConsoleLoggerWithChild(prefix, minLevel = "debug", baseContext = {}) {
+  const levels = ["debug", "info", "warn", "error"];
+  const shouldLog = (level) => levels.indexOf(level) >= levels.indexOf(minLevel);
+  const formatContext = (context) => {
+    const merged = { ...baseContext, ...context };
+    const entries = Object.entries(merged).filter(([key]) => key !== "context").map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+    return entries ? ` ${entries}` : "";
+  };
+  const logger = {
+    debug: (message, context) => {
+      if (shouldLog("debug")) {
+        console.debug(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    info: (message, context) => {
+      if (shouldLog("info")) {
+        console.info(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    warn: (message, context) => {
+      if (shouldLog("warn")) {
+        console.warn(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    error: (message, context, error) => {
+      if (shouldLog("error")) {
+        console.error(
+          `[${prefix}] ${message}${formatContext(context)}`,
+          error ? `
+${error.stack || error.message}` : ""
+        );
+      }
+    },
+    child: (additionalContext) => {
+      return createConsoleLoggerWithChild(prefix, minLevel, {
+        ...baseContext,
+        ...additionalContext
+      });
+    }
+  };
+  return logger;
+}
+function createPluginLogger(pluginName, minLevel = "debug") {
+  const coreFactory = getCoreLoggerFactory();
+  if (coreFactory) {
+    return coreFactory(pluginName);
+  }
+  return createConsoleLoggerWithChild(pluginName, minLevel);
+}
+function getLogLevelFromEnv() {
+  if (typeof process !== "undefined" && process.env) {
+    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;
+    if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+      return envLevel;
+    }
+  }
+  return "info";
+}
+
+// src/logging/index.ts
+var import_plugin_types = require("@quilltap/plugin-types");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  __clearCoreLoggerFactory,
+  __injectCoreLoggerFactory,
+  createConsoleLogger,
+  createNoopLogger,
+  createPluginLogger,
+  getLogLevelFromEnv,
+  hasCoreLogger
+});
+//# sourceMappingURL=index.js.map

package/dist/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/logging/index.ts","../../src/logging/plugin-logger.ts"],"sourcesContent":["/**\n * Logging Utilities\n *\n * Exports the plugin logger bridge and related utilities.\n *\n * @module @quilltap/plugin-utils/logging\n */\n\nexport {\n  createPluginLogger,\n  hasCoreLogger,\n  getLogLevelFromEnv,\n  __injectCoreLoggerFactory,\n  __clearCoreLoggerFactory,\n} from './plugin-logger';\n\nexport type { PluginLoggerWithChild } from './plugin-logger';\n\n// Re-export logger types from plugin-types\nexport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n// Re-export logger utilities from plugin-types for convenience\nexport { createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';\n","/**\n * Plugin Logger Bridge\n *\n * Provides a logger factory for plugins that automatically bridges\n * to Quilltap's core logging when running inside the host application,\n * or falls back to console logging when running standalone.\n *\n * @module @quilltap/plugin-utils/logging/plugin-logger\n */\n\nimport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n/**\n * Extended logger interface with child logger support\n */\nexport interface PluginLoggerWithChild extends PluginLogger {\n  /**\n   * Create a child logger with additional context\n   * @param additionalContext Context to merge with parent context\n   * @returns A new logger with combined context\n   */\n  child(additionalContext: LogContext): PluginLoggerWithChild;\n}\n\n/**\n * Type for the global Quilltap logger bridge\n * Stored on globalThis to work across different npm package copies\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __quilltap_logger_factory:\n    | ((pluginName: string) => PluginLoggerWithChild)\n    | undefined;\n}\n\n/**\n * Get the core logger factory from global namespace\n *\n * @returns The injected factory or null if not in Quilltap environment\n */\nfunction getCoreLoggerFactory(): ((pluginName: string) => PluginLoggerWithChild) | null {\n  return globalThis.__quilltap_logger_factory ?? null;\n}\n\n/**\n * Inject the core logger factory from Quilltap host\n *\n * This is called by Quilltap core when loading plugins to bridge\n * plugin logging into the host's logging system. Uses globalThis\n * to ensure it works even when plugins have their own copy of\n * plugin-utils in their node_modules.\n *\n * **Internal API - not for plugin use**\n *\n * @param factory A function that creates a child logger for a plugin\n */\nexport function __injectCoreLoggerFactory(\n  factory: (pluginName: string) => PluginLoggerWithChild\n): void {\n  globalThis.__quilltap_logger_factory = factory;\n}\n\n/**\n * Clear the injected core logger factory\n *\n * Useful for testing or when unloading the plugin system.\n *\n * **Internal API - not for plugin use**\n */\nexport function __clearCoreLoggerFactory(): void {\n  globalThis.__quilltap_logger_factory = undefined;\n}\n\n/**\n * Check if a core logger has been injected\n *\n * @returns True if running inside Quilltap with core logging available\n */\nexport function hasCoreLogger(): boolean {\n  return getCoreLoggerFactory() !== null;\n}\n\n/**\n * Create a console logger with child support\n *\n * @param prefix Logger prefix\n * @param minLevel Minimum log level\n * @param baseContext Base context to include in all logs\n */\nfunction createConsoleLoggerWithChild(\n  prefix: string,\n  minLevel: LogLevel = 'debug',\n  baseContext: LogContext = {}\n): PluginLoggerWithChild {\n  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];\n  const shouldLog = (level: LogLevel): boolean =>\n    levels.indexOf(level) >= levels.indexOf(minLevel);\n\n  const formatContext = (context?: LogContext): string => {\n    const merged = { ...baseContext, ...context };\n    const entries = Object.entries(merged)\n      .filter(([key]) => key !== 'context')\n      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n      .join(' ');\n    return entries ? ` ${entries}` : '';\n  };\n\n  const logger: PluginLoggerWithChild = {\n    debug: (message: string, context?: LogContext): void => {\n      if (shouldLog('debug')) {\n        console.debug(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    info: (message: string, context?: LogContext): void => {\n      if (shouldLog('info')) {\n        console.info(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    warn: (message: string, context?: LogContext): void => {\n      if (shouldLog('warn')) {\n        console.warn(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    error: (message: string, context?: LogContext, error?: Error): void => {\n      if (shouldLog('error')) {\n        console.error(\n          `[${prefix}] ${message}${formatContext(context)}`,\n          error ? `\\n${error.stack || error.message}` : ''\n        );\n      }\n    },\n\n    child: (additionalContext: LogContext): PluginLoggerWithChild => {\n      return createConsoleLoggerWithChild(prefix, minLevel, {\n        ...baseContext,\n        ...additionalContext,\n      });\n    },\n  };\n\n  return logger;\n}\n\n/**\n * Create a plugin logger that bridges to Quilltap core logging\n *\n * When running inside Quilltap:\n * - Routes all logs to the core logger\n * - Tags logs with `{ plugin: pluginName, module: 'plugin' }`\n * - Logs appear in Quilltap's combined.log and console\n *\n * When running standalone:\n * - Falls back to console logging with `[pluginName]` prefix\n * - Respects the specified minimum log level\n *\n * @param pluginName - The plugin identifier (e.g., 'qtap-plugin-openai')\n * @param minLevel - Minimum log level when running standalone (default: 'debug')\n * @returns A logger instance\n *\n * @example\n * ```typescript\n * // In your plugin's provider.ts\n * import { createPluginLogger } from '@quilltap/plugin-utils';\n *\n * const logger = createPluginLogger('qtap-plugin-my-provider');\n *\n * export class MyProvider implements LLMProvider {\n *   async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {\n *     logger.debug('Sending message', { model: params.model });\n *\n *     try {\n *       const response = await this.client.chat({...});\n *       logger.info('Received response', { tokens: response.usage?.total_tokens });\n *       return response;\n *     } catch (error) {\n *       logger.error('Failed to send message', { model: params.model }, error as Error);\n *       throw error;\n *     }\n *   }\n * }\n * ```\n */\nexport function createPluginLogger(\n  pluginName: string,\n  minLevel: LogLevel = 'debug'\n): PluginLoggerWithChild {\n  // Check for core logger factory from global namespace\n  const coreFactory = getCoreLoggerFactory();\n  if (coreFactory) {\n    return coreFactory(pluginName);\n  }\n\n  // Standalone mode: use enhanced console logger\n  return createConsoleLoggerWithChild(pluginName, minLevel);\n}\n\n/**\n * Get the minimum log level from environment\n *\n * Checks for LOG_LEVEL or QUILTTAP_LOG_LEVEL environment variables.\n * Useful for configuring standalone plugin logging.\n *\n * @returns The configured log level, or 'info' as default\n */\nexport function getLogLevelFromEnv(): LogLevel {\n  if (typeof process !== 'undefined' && process.env) {\n    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;\n    if (envLevel && ['debug', 'info', 'warn', 'error'].includes(envLevel)) {\n      return envLevel as LogLevel;\n    }\n  }\n  return 'info';\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwCA,SAAS,uBAA+E;AACtF,SAAO,WAAW,6BAA6B;AACjD;AAcO,SAAS,0BACd,SACM;AACN,aAAW,4BAA4B;AACzC;AASO,SAAS,2BAAiC;AAC/C,aAAW,4BAA4B;AACzC;AAOO,SAAS,gBAAyB;AACvC,SAAO,qBAAqB,MAAM;AACpC;AASA,SAAS,6BACP,QACA,WAAqB,SACrB,cAA0B,CAAC,GACJ;AACvB,QAAM,SAAqB,CAAC,SAAS,QAAQ,QAAQ,OAAO;AAC5D,QAAM,YAAY,CAAC,UACjB,OAAO,QAAQ,KAAK,KAAK,OAAO,QAAQ,QAAQ;AAElD,QAAM,gBAAgB,CAAC,YAAiC;AACtD,UAAM,SAAS,EAAE,GAAG,aAAa,GAAG,QAAQ;AAC5C,UAAM,UAAU,OAAO,QAAQ,MAAM,EAClC,OAAO,CAAC,CAAC,GAAG,MAAM,QAAQ,SAAS,EACnC,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,GAAG,GAAG,IAAI,KAAK,UAAU,KAAK,CAAC,EAAE,EACvD,KAAK,GAAG;AACX,WAAO,UAAU,IAAI,OAAO,KAAK;AAAA,EACnC;AAEA,QAAM,SAAgC;AAAA,IACpC,OAAO,CAAC,SAAiB,YAA+B;AACtD,UAAI,UAAU,OAAO,GAAG;AACtB,gBAAQ,MAAM,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MACjE;AAAA,IACF;AAAA,IAEA,MAAM,CAAC,SAAiB,YAA+B;AACrD,UAAI,UAAU,MAAM,GAAG;AACrB,gBAAQ,KAAK,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MAChE;AAAA,IACF;AAAA,IAEA,MAAM,CAAC,SAAiB,YAA+B;AACrD,UAAI,UAAU,MAAM,GAAG;AACrB,gBAAQ,KAAK,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MAChE;AAAA,IACF;AAAA,IAEA,OAAO,CAAC,SAAiB,SAAsB,UAAwB;AACrE,UAAI,UAAU,OAAO,GAAG;AACtB,gBAAQ;AAAA,UACN,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC;AAAA,UAC/C,QAAQ;AAAA,EAAK,MAAM,SAAS,MAAM,OAAO,KAAK;AAAA,QAChD;AAAA,MACF;AAAA,IACF;AAAA,IAEA,OAAO,CAAC,sBAAyD;AAC/D,aAAO,6BAA6B,QAAQ,UAAU;AAAA,QACpD,GAAG;AAAA,QACH,GAAG;AAAA,MACL,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;AAyCO,SAAS,mBACd,YACA,WAAqB,SACE;AAEvB,QAAM,cAAc,qBAAqB;AACzC,MAAI,aAAa;AACf,WAAO,YAAY,UAAU;AAAA,EAC/B;AAGA,SAAO,6BAA6B,YAAY,QAAQ;AAC1D;AAUO,SAAS,qBAA+B;AAC7C,MAAI,OAAO,YAAY,eAAe,QAAQ,KAAK;AACjD,UAAM,WAAW,QAAQ,IAAI,aAAa,QAAQ,IAAI;AACtD,QAAI,YAAY,CAAC,SAAS,QAAQ,QAAQ,OAAO,EAAE,SAAS,QAAQ,GAAG;AACrE,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;;;ADjMA,0BAAsD;","names":[]}

package/dist/logging/index.mjs

@@ -0,0 +1,84 @@
+// src/logging/plugin-logger.ts
+function getCoreLoggerFactory() {
+  return globalThis.__quilltap_logger_factory ?? null;
+}
+function __injectCoreLoggerFactory(factory) {
+  globalThis.__quilltap_logger_factory = factory;
+}
+function __clearCoreLoggerFactory() {
+  globalThis.__quilltap_logger_factory = void 0;
+}
+function hasCoreLogger() {
+  return getCoreLoggerFactory() !== null;
+}
+function createConsoleLoggerWithChild(prefix, minLevel = "debug", baseContext = {}) {
+  const levels = ["debug", "info", "warn", "error"];
+  const shouldLog = (level) => levels.indexOf(level) >= levels.indexOf(minLevel);
+  const formatContext = (context) => {
+    const merged = { ...baseContext, ...context };
+    const entries = Object.entries(merged).filter(([key]) => key !== "context").map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+    return entries ? ` ${entries}` : "";
+  };
+  const logger = {
+    debug: (message, context) => {
+      if (shouldLog("debug")) {
+        console.debug(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    info: (message, context) => {
+      if (shouldLog("info")) {
+        console.info(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    warn: (message, context) => {
+      if (shouldLog("warn")) {
+        console.warn(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    error: (message, context, error) => {
+      if (shouldLog("error")) {
+        console.error(
+          `[${prefix}] ${message}${formatContext(context)}`,
+          error ? `
+${error.stack || error.message}` : ""
+        );
+      }
+    },
+    child: (additionalContext) => {
+      return createConsoleLoggerWithChild(prefix, minLevel, {
+        ...baseContext,
+        ...additionalContext
+      });
+    }
+  };
+  return logger;
+}
+function createPluginLogger(pluginName, minLevel = "debug") {
+  const coreFactory = getCoreLoggerFactory();
+  if (coreFactory) {
+    return coreFactory(pluginName);
+  }
+  return createConsoleLoggerWithChild(pluginName, minLevel);
+}
+function getLogLevelFromEnv() {
+  if (typeof process !== "undefined" && process.env) {
+    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;
+    if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+      return envLevel;
+    }
+  }
+  return "info";
+}
+
+// src/logging/index.ts
+import { createConsoleLogger, createNoopLogger } from "@quilltap/plugin-types";
+export {
+  __clearCoreLoggerFactory,
+  __injectCoreLoggerFactory,
+  createConsoleLogger,
+  createNoopLogger,
+  createPluginLogger,
+  getLogLevelFromEnv,
+  hasCoreLogger
+};
+//# sourceMappingURL=index.mjs.map

package/dist/logging/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/logging/plugin-logger.ts","../../src/logging/index.ts"],"sourcesContent":["/**\n * Plugin Logger Bridge\n *\n * Provides a logger factory for plugins that automatically bridges\n * to Quilltap's core logging when running inside the host application,\n * or falls back to console logging when running standalone.\n *\n * @module @quilltap/plugin-utils/logging/plugin-logger\n */\n\nimport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n/**\n * Extended logger interface with child logger support\n */\nexport interface PluginLoggerWithChild extends PluginLogger {\n  /**\n   * Create a child logger with additional context\n   * @param additionalContext Context to merge with parent context\n   * @returns A new logger with combined context\n   */\n  child(additionalContext: LogContext): PluginLoggerWithChild;\n}\n\n/**\n * Type for the global Quilltap logger bridge\n * Stored on globalThis to work across different npm package copies\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __quilltap_logger_factory:\n    | ((pluginName: string) => PluginLoggerWithChild)\n    | undefined;\n}\n\n/**\n * Get the core logger factory from global namespace\n *\n * @returns The injected factory or null if not in Quilltap environment\n */\nfunction getCoreLoggerFactory(): ((pluginName: string) => PluginLoggerWithChild) | null {\n  return globalThis.__quilltap_logger_factory ?? null;\n}\n\n/**\n * Inject the core logger factory from Quilltap host\n *\n * This is called by Quilltap core when loading plugins to bridge\n * plugin logging into the host's logging system. Uses globalThis\n * to ensure it works even when plugins have their own copy of\n * plugin-utils in their node_modules.\n *\n * **Internal API - not for plugin use**\n *\n * @param factory A function that creates a child logger for a plugin\n */\nexport function __injectCoreLoggerFactory(\n  factory: (pluginName: string) => PluginLoggerWithChild\n): void {\n  globalThis.__quilltap_logger_factory = factory;\n}\n\n/**\n * Clear the injected core logger factory\n *\n * Useful for testing or when unloading the plugin system.\n *\n * **Internal API - not for plugin use**\n */\nexport function __clearCoreLoggerFactory(): void {\n  globalThis.__quilltap_logger_factory = undefined;\n}\n\n/**\n * Check if a core logger has been injected\n *\n * @returns True if running inside Quilltap with core logging available\n */\nexport function hasCoreLogger(): boolean {\n  return getCoreLoggerFactory() !== null;\n}\n\n/**\n * Create a console logger with child support\n *\n * @param prefix Logger prefix\n * @param minLevel Minimum log level\n * @param baseContext Base context to include in all logs\n */\nfunction createConsoleLoggerWithChild(\n  prefix: string,\n  minLevel: LogLevel = 'debug',\n  baseContext: LogContext = {}\n): PluginLoggerWithChild {\n  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];\n  const shouldLog = (level: LogLevel): boolean =>\n    levels.indexOf(level) >= levels.indexOf(minLevel);\n\n  const formatContext = (context?: LogContext): string => {\n    const merged = { ...baseContext, ...context };\n    const entries = Object.entries(merged)\n      .filter(([key]) => key !== 'context')\n      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n      .join(' ');\n    return entries ? ` ${entries}` : '';\n  };\n\n  const logger: PluginLoggerWithChild = {\n    debug: (message: string, context?: LogContext): void => {\n      if (shouldLog('debug')) {\n        console.debug(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    info: (message: string, context?: LogContext): void => {\n      if (shouldLog('info')) {\n        console.info(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    warn: (message: string, context?: LogContext): void => {\n      if (shouldLog('warn')) {\n        console.warn(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    error: (message: string, context?: LogContext, error?: Error): void => {\n      if (shouldLog('error')) {\n        console.error(\n          `[${prefix}] ${message}${formatContext(context)}`,\n          error ? `\\n${error.stack || error.message}` : ''\n        );\n      }\n    },\n\n    child: (additionalContext: LogContext): PluginLoggerWithChild => {\n      return createConsoleLoggerWithChild(prefix, minLevel, {\n        ...baseContext,\n        ...additionalContext,\n      });\n    },\n  };\n\n  return logger;\n}\n\n/**\n * Create a plugin logger that bridges to Quilltap core logging\n *\n * When running inside Quilltap:\n * - Routes all logs to the core logger\n * - Tags logs with `{ plugin: pluginName, module: 'plugin' }`\n * - Logs appear in Quilltap's combined.log and console\n *\n * When running standalone:\n * - Falls back to console logging with `[pluginName]` prefix\n * - Respects the specified minimum log level\n *\n * @param pluginName - The plugin identifier (e.g., 'qtap-plugin-openai')\n * @param minLevel - Minimum log level when running standalone (default: 'debug')\n * @returns A logger instance\n *\n * @example\n * ```typescript\n * // In your plugin's provider.ts\n * import { createPluginLogger } from '@quilltap/plugin-utils';\n *\n * const logger = createPluginLogger('qtap-plugin-my-provider');\n *\n * export class MyProvider implements LLMProvider {\n *   async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {\n *     logger.debug('Sending message', { model: params.model });\n *\n *     try {\n *       const response = await this.client.chat({...});\n *       logger.info('Received response', { tokens: response.usage?.total_tokens });\n *       return response;\n *     } catch (error) {\n *       logger.error('Failed to send message', { model: params.model }, error as Error);\n *       throw error;\n *     }\n *   }\n * }\n * ```\n */\nexport function createPluginLogger(\n  pluginName: string,\n  minLevel: LogLevel = 'debug'\n): PluginLoggerWithChild {\n  // Check for core logger factory from global namespace\n  const coreFactory = getCoreLoggerFactory();\n  if (coreFactory) {\n    return coreFactory(pluginName);\n  }\n\n  // Standalone mode: use enhanced console logger\n  return createConsoleLoggerWithChild(pluginName, minLevel);\n}\n\n/**\n * Get the minimum log level from environment\n *\n * Checks for LOG_LEVEL or QUILTTAP_LOG_LEVEL environment variables.\n * Useful for configuring standalone plugin logging.\n *\n * @returns The configured log level, or 'info' as default\n */\nexport function getLogLevelFromEnv(): LogLevel {\n  if (typeof process !== 'undefined' && process.env) {\n    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;\n    if (envLevel && ['debug', 'info', 'warn', 'error'].includes(envLevel)) {\n      return envLevel as LogLevel;\n    }\n  }\n  return 'info';\n}\n","/**\n * Logging Utilities\n *\n * Exports the plugin logger bridge and related utilities.\n *\n * @module @quilltap/plugin-utils/logging\n */\n\nexport {\n  createPluginLogger,\n  hasCoreLogger,\n  getLogLevelFromEnv,\n  __injectCoreLoggerFactory,\n  __clearCoreLoggerFactory,\n} from './plugin-logger';\n\nexport type { PluginLoggerWithChild } from './plugin-logger';\n\n// Re-export logger types from plugin-types\nexport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n// Re-export logger utilities from plugin-types for convenience\nexport { createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';\n"],"mappings":";AAwCA,SAAS,uBAA+E;AACtF,SAAO,WAAW,6BAA6B;AACjD;AAcO,SAAS,0BACd,SACM;AACN,aAAW,4BAA4B;AACzC;AASO,SAAS,2BAAiC;AAC/C,aAAW,4BAA4B;AACzC;AAOO,SAAS,gBAAyB;AACvC,SAAO,qBAAqB,MAAM;AACpC;AASA,SAAS,6BACP,QACA,WAAqB,SACrB,cAA0B,CAAC,GACJ;AACvB,QAAM,SAAqB,CAAC,SAAS,QAAQ,QAAQ,OAAO;AAC5D,QAAM,YAAY,CAAC,UACjB,OAAO,QAAQ,KAAK,KAAK,OAAO,QAAQ,QAAQ;AAElD,QAAM,gBAAgB,CAAC,YAAiC;AACtD,UAAM,SAAS,EAAE,GAAG,aAAa,GAAG,QAAQ;AAC5C,UAAM,UAAU,OAAO,QAAQ,MAAM,EAClC,OAAO,CAAC,CAAC,GAAG,MAAM,QAAQ,SAAS,EACnC,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,GAAG,GAAG,IAAI,KAAK,UAAU,KAAK,CAAC,EAAE,EACvD,KAAK,GAAG;AACX,WAAO,UAAU,IAAI,OAAO,KAAK;AAAA,EACnC;AAEA,QAAM,SAAgC;AAAA,IACpC,OAAO,CAAC,SAAiB,YAA+B;AACtD,UAAI,UAAU,OAAO,GAAG;AACtB,gBAAQ,MAAM,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MACjE;AAAA,IACF;AAAA,IAEA,MAAM,CAAC,SAAiB,YAA+B;AACrD,UAAI,UAAU,MAAM,GAAG;AACrB,gBAAQ,KAAK,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MAChE;AAAA,IACF;AAAA,IAEA,MAAM,CAAC,SAAiB,YAA+B;AACrD,UAAI,UAAU,MAAM,GAAG;AACrB,gBAAQ,KAAK,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC,EAAE;AAAA,MAChE;AAAA,IACF;AAAA,IAEA,OAAO,CAAC,SAAiB,SAAsB,UAAwB;AACrE,UAAI,UAAU,OAAO,GAAG;AACtB,gBAAQ;AAAA,UACN,IAAI,MAAM,KAAK,OAAO,GAAG,cAAc,OAAO,CAAC;AAAA,UAC/C,QAAQ;AAAA,EAAK,MAAM,SAAS,MAAM,OAAO,KAAK;AAAA,QAChD;AAAA,MACF;AAAA,IACF;AAAA,IAEA,OAAO,CAAC,sBAAyD;AAC/D,aAAO,6BAA6B,QAAQ,UAAU;AAAA,QACpD,GAAG;AAAA,QACH,GAAG;AAAA,MACL,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;AAyCO,SAAS,mBACd,YACA,WAAqB,SACE;AAEvB,QAAM,cAAc,qBAAqB;AACzC,MAAI,aAAa;AACf,WAAO,YAAY,UAAU;AAAA,EAC/B;AAGA,SAAO,6BAA6B,YAAY,QAAQ;AAC1D;AAUO,SAAS,qBAA+B;AAC7C,MAAI,OAAO,YAAY,eAAe,QAAQ,KAAK;AACjD,UAAM,WAAW,QAAQ,IAAI,aAAa,QAAQ,IAAI;AACtD,QAAI,YAAY,CAAC,SAAS,QAAQ,QAAQ,OAAO,EAAE,SAAS,QAAQ,GAAG;AACrE,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;;;ACjMA,SAAS,qBAAqB,wBAAwB;","names":[]}

package/dist/tools/index.d.mts

@@ -0,0 +1,236 @@
+import { ToolCallRequest, UniversalTool, AnthropicToolDefinition, GoogleToolDefinition } from '@quilltap/plugin-types';
+export { AnthropicToolDefinition, GoogleToolDefinition, OpenAIToolDefinition, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool } from '@quilltap/plugin-types';
+
+/**
+ * Tool Call Parsers
+ *
+ * Provider-specific parsers for extracting tool calls from LLM responses.
+ * Each parser converts from a provider's native format to the standardized
+ * ToolCallRequest format.
+ *
+ * @module @quilltap/plugin-utils/tools/parsers
+ */
+
+/**
+ * Supported tool call response formats
+ */
+type ToolCallFormat = 'openai' | 'anthropic' | 'google' | 'auto';
+/**
+ * Parse OpenAI format tool calls from LLM response
+ *
+ * Extracts tool calls from OpenAI/Grok API responses which return
+ * tool_calls in the message object.
+ *
+ * Expected response structures:
+ * - `response.tool_calls` (direct)
+ * - `response.choices[0].message.tool_calls` (nested)
+ *
+ * @param response - The raw response from provider API
+ * @returns Array of parsed tool call requests
+ *
+ * @example
+ * ```typescript
+ * const response = await openai.chat.completions.create({...});
+ * const toolCalls = parseOpenAIToolCalls(response);
+ * // Returns: [{ name: 'search_web', arguments: { query: 'hello' } }]
+ * ```
+ */
+declare function parseOpenAIToolCalls(response: unknown): ToolCallRequest[];
+/**
+ * Parse Anthropic format tool calls from LLM response
+ *
+ * Extracts tool calls from Anthropic API responses which return
+ * tool_use blocks in the content array.
+ *
+ * Expected response structure:
+ * - `response.content` array with `{ type: 'tool_use', name, input }`
+ *
+ * @param response - The raw response from provider API
+ * @returns Array of parsed tool call requests
+ *
+ * @example
+ * ```typescript
+ * const response = await anthropic.messages.create({...});
+ * const toolCalls = parseAnthropicToolCalls(response);
+ * // Returns: [{ name: 'search_web', arguments: { query: 'hello' } }]
+ * ```
+ */
+declare function parseAnthropicToolCalls(response: unknown): ToolCallRequest[];
+/**
+ * Parse Google Gemini format tool calls from LLM response
+ *
+ * Extracts tool calls from Google Gemini API responses which return
+ * functionCall objects in the parts array.
+ *
+ * Expected response structure:
+ * - `response.candidates[0].content.parts` array with `{ functionCall: { name, args } }`
+ *
+ * @param response - The raw response from provider API
+ * @returns Array of parsed tool call requests
+ *
+ * @example
+ * ```typescript
+ * const response = await gemini.generateContent({...});
+ * const toolCalls = parseGoogleToolCalls(response);
+ * // Returns: [{ name: 'search_web', arguments: { query: 'hello' } }]
+ * ```
+ */
+declare function parseGoogleToolCalls(response: unknown): ToolCallRequest[];
+/**
+ * Detect the format of a tool call response
+ *
+ * Analyzes the response structure to determine which provider format it uses.
+ *
+ * @param response - The raw response from a provider API
+ * @returns The detected format, or null if unrecognized
+ */
+declare function detectToolCallFormat(response: unknown): ToolCallFormat | null;
+/**
+ * Parse tool calls with auto-detection or explicit format
+ *
+ * A unified parser that can either auto-detect the response format
+ * or use a specified format. This is useful when you're not sure
+ * which provider's response you're handling.
+ *
+ * @param response - The raw response from a provider API
+ * @param format - The format to use: 'openai', 'anthropic', 'google', or 'auto'
+ * @returns Array of parsed tool call requests
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect format
+ * const toolCalls = parseToolCalls(response, 'auto');
+ *
+ * // Or specify format explicitly
+ * const toolCalls = parseToolCalls(response, 'openai');
+ * ```
+ */
+declare function parseToolCalls(response: unknown, format?: ToolCallFormat): ToolCallRequest[];
+/**
+ * Check if a response contains tool calls
+ *
+ * Quick check to determine if a response has any tool calls
+ * without fully parsing them.
+ *
+ * @param response - The raw response from a provider API
+ * @returns True if the response contains tool calls
+ */
+declare function hasToolCalls(response: unknown): boolean;
+
+/**
+ * Tool Format Converters
+ *
+ * Utilities for converting between different provider tool formats.
+ * The universal format (OpenAI-style) serves as the baseline for all conversions.
+ *
+ * @module @quilltap/plugin-utils/tools/converters
+ */
+
+/**
+ * Convert OpenAI/Universal format tool to Anthropic format
+ *
+ * Anthropic uses a tool_use format with:
+ * - name: string
+ * - description: string
+ * - input_schema: JSON schema object
+ *
+ * @param tool - Universal tool in OpenAI format
+ * @returns Tool formatted for Anthropic's tool_use
+ *
+ * @example
+ * ```typescript
+ * const anthropicTool = convertToAnthropicFormat(universalTool);
+ * // Returns: {
+ * //   name: 'search_web',
+ * //   description: 'Search the web',
+ * //   input_schema: {
+ * //     type: 'object',
+ * //     properties: { query: { type: 'string' } },
+ * //     required: ['query']
+ * //   }
+ * // }
+ * ```
+ */
+declare function convertToAnthropicFormat(tool: UniversalTool): AnthropicToolDefinition;
+/**
+ * Convert OpenAI/Universal format tool to Google Gemini format
+ *
+ * Google uses a function calling format with:
+ * - name: string
+ * - description: string
+ * - parameters: JSON schema object
+ *
+ * @param tool - Universal tool in OpenAI format
+ * @returns Tool formatted for Google's functionCall
+ *
+ * @example
+ * ```typescript
+ * const googleTool = convertToGoogleFormat(universalTool);
+ * // Returns: {
+ * //   name: 'search_web',
+ * //   description: 'Search the web',
+ * //   parameters: {
+ * //     type: 'object',
+ * //     properties: { query: { type: 'string' } },
+ * //     required: ['query']
+ * //   }
+ * // }
+ * ```
+ */
+declare function convertToGoogleFormat(tool: UniversalTool): GoogleToolDefinition;
+/**
+ * Convert Anthropic format tool to Universal/OpenAI format
+ *
+ * @param tool - Anthropic format tool
+ * @returns Tool in universal OpenAI format
+ */
+declare function convertFromAnthropicFormat(tool: AnthropicToolDefinition): UniversalTool;
+/**
+ * Convert Google format tool to Universal/OpenAI format
+ *
+ * @param tool - Google format tool
+ * @returns Tool in universal OpenAI format
+ */
+declare function convertFromGoogleFormat(tool: GoogleToolDefinition): UniversalTool;
+/**
+ * Apply prompt/description length limit to a tool
+ *
+ * Modifies a tool's description if it exceeds maxBytes, appending a warning
+ * that the description was truncated. This is useful for providers with
+ * strict token limits.
+ *
+ * @param tool - Tool object (any format) with a description property
+ * @param maxBytes - Maximum bytes allowed for description (including warning)
+ * @returns Modified tool with truncated description if needed
+ *
+ * @example
+ * ```typescript
+ * const limitedTool = applyDescriptionLimit(tool, 500);
+ * // If description > 500 bytes, truncates and adds warning
+ * ```
+ */
+declare function applyDescriptionLimit<T extends {
+    description: string;
+}>(tool: T, maxBytes: number): T;
+/**
+ * Target format for tool conversion
+ */
+type ToolConvertTarget = 'openai' | 'anthropic' | 'google';
+/**
+ * Convert a universal tool to a specific provider format
+ *
+ * @param tool - Universal tool in OpenAI format
+ * @param target - Target provider format
+ * @returns Tool in the target format
+ */
+declare function convertToolTo(tool: UniversalTool, target: ToolConvertTarget): UniversalTool | AnthropicToolDefinition | GoogleToolDefinition;
+/**
+ * Convert multiple tools to a specific provider format
+ *
+ * @param tools - Array of universal tools
+ * @param target - Target provider format
+ * @returns Array of tools in the target format
+ */
+declare function convertToolsTo(tools: UniversalTool[], target: ToolConvertTarget): Array<UniversalTool | AnthropicToolDefinition | GoogleToolDefinition>;
+
+export { type ToolCallFormat, type ToolConvertTarget, applyDescriptionLimit, convertFromAnthropicFormat, convertFromGoogleFormat, convertToAnthropicFormat, convertToGoogleFormat, convertToolTo, convertToolsTo, detectToolCallFormat, hasToolCalls, parseAnthropicToolCalls, parseGoogleToolCalls, parseOpenAIToolCalls, parseToolCalls };