@quilltap/plugin-utils 1.2.5 → 1.4.0

package/dist/index.d.mts

@@ -3,6 +3,52 @@ export { ToolCallFormat, ToolConvertTarget, applyDescriptionLimit, convertFromAn
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.mjs';
 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';
+
+/**
+ * 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)
+ * - `search_help` - Search Quilltap help documentation
+ */
+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 +70,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.4.0";
 
-export { PLUGIN_UTILS_VERSION };
+export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, getBuiltinToolNames };

package/dist/index.d.ts

@@ -3,6 +3,52 @@ export { ToolCallFormat, ToolConvertTarget, applyDescriptionLimit, convertFromAn
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.js';
 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';
+
+/**
+ * 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)
+ * - `search_help` - Search Quilltap help documentation
+ */
+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 +70,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.4.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,13 +50,17 @@ __export(src_exports, {
   createRoleplayTemplatePlugin: () => createRoleplayTemplatePlugin,
   createSingleTemplatePlugin: () => createSingleTemplatePlugin,
   detectToolCallFormat: () => detectToolCallFormat,
+  getBuiltinToolNames: () => getBuiltinToolNames,
   getLogLevelFromEnv: () => getLogLevelFromEnv,
   hasCoreLogger: () => hasCoreLogger,
   hasToolCalls: () => hasToolCalls,
+  isVMEnvironment: () => isVMEnvironment,
   parseAnthropicToolCalls: () => parseAnthropicToolCalls,
   parseGoogleToolCalls: () => parseGoogleToolCalls,
   parseOpenAIToolCalls: () => parseOpenAIToolCalls,
   parseToolCalls: () => parseToolCalls,
+  resolveHostGateway: () => resolveHostGateway,
+  rewriteLocalhostUrl: () => rewriteLocalhostUrl,
   validateRoleplayTemplatePlugin: () => validateRoleplayTemplatePlugin,
   validateTemplateConfig: () => validateTemplateConfig
 });
@@ -731,10 +736,139 @@ 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",
+  "search_help"
+]);
+function getBuiltinToolNames() {
+  return new Set(BUILTIN_TOOL_NAMES);
+}
+
+// src/host-rewrite.ts
+var import_node_fs = require("fs");
+var LOCALHOST_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "[::1]",
+  "::1"
+]);
+var cachedGatewayHost;
+var rewriteLogger = createPluginLogger("host-rewrite");
+function isLimaEnvironment() {
+  return process.env.LIMA_CONTAINER === "true";
+}
+function isDockerEnvironment() {
+  if (process.env.DOCKER_CONTAINER === "true") {
+    return true;
+  }
+  try {
+    if ((0, import_node_fs.existsSync)("/.dockerenv")) {
+      return true;
+    }
+    const appStat = (0, import_node_fs.statSync)("/app");
+    if (appStat.isDirectory()) {
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function isVMEnvironment() {
+  return isDockerEnvironment() || isLimaEnvironment();
+}
+function resolveHostGateway() {
+  if (cachedGatewayHost !== void 0) {
+    return cachedGatewayHost;
+  }
+  const envIP = process.env.QUILLTAP_HOST_IP;
+  if (envIP) {
+    rewriteLogger.info("Host gateway from QUILLTAP_HOST_IP", { host: envIP });
+    cachedGatewayHost = envIP;
+    return cachedGatewayHost;
+  }
+  if (isDockerEnvironment() && !isLimaEnvironment()) {
+    rewriteLogger.info("Docker environment detected \u2014 using host.docker.internal as gateway hostname");
+    cachedGatewayHost = "host.docker.internal";
+    return cachedGatewayHost;
+  }
+  try {
+    const routeTable = (0, import_node_fs.readFileSync)("/proc/net/route", "utf-8");
+    for (const line of routeTable.split("\n").slice(1)) {
+      const fields = line.trim().split("	");
+      if (fields.length >= 3 && fields[1] === "00000000") {
+        const hexGateway = fields[2];
+        const ip = [
+          parseInt(hexGateway.substring(6, 8), 16),
+          parseInt(hexGateway.substring(4, 6), 16),
+          parseInt(hexGateway.substring(2, 4), 16),
+          parseInt(hexGateway.substring(0, 2), 16)
+        ].join(".");
+        rewriteLogger.info("Host gateway IP from /proc/net/route", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /proc/net/route for default gateway lookup");
+  }
+  try {
+    const hosts = (0, import_node_fs.readFileSync)("/etc/hosts", "utf-8");
+    for (const line of hosts.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || trimmed === "") continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts.length >= 2 && parts.slice(1).includes("host.docker.internal")) {
+        const ip = parts[0];
+        rewriteLogger.info("Host gateway IP from /etc/hosts (host.docker.internal)", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /etc/hosts for host.docker.internal lookup");
+  }
+  rewriteLogger.warn("Could not resolve host gateway \u2014 localhost URLs will not be rewritten");
+  cachedGatewayHost = null;
+  return cachedGatewayHost;
+}
+function rewriteLocalhostUrl(url) {
+  if (!isVMEnvironment()) {
+    return url;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+  if (!LOCALHOST_HOSTS.has(parsed.hostname)) {
+    return url;
+  }
+  const gatewayHost = resolveHostGateway();
+  if (!gatewayHost) {
+    return url;
+  }
+  parsed.hostname = gatewayHost;
+  const rewritten = parsed.toString();
+  rewriteLogger.debug("Rewrote localhost URL", {
+    original: url,
+    rewritten,
+    gatewayHost
+  });
+  return rewritten;
+}
+
 // src/index.ts
-var PLUGIN_UTILS_VERSION = "1.2.0";
+var PLUGIN_UTILS_VERSION = "1.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_TOOL_NAMES,
   OpenAICompatibleProvider,
   PLUGIN_UTILS_VERSION,
   __clearCoreLoggerFactory,
@@ -754,13 +888,17 @@ var PLUGIN_UTILS_VERSION = "1.2.0";
   createRoleplayTemplatePlugin,
   createSingleTemplatePlugin,
   detectToolCallFormat,
+  getBuiltinToolNames,
   getLogLevelFromEnv,
   hasCoreLogger,
   hasToolCalls,
+  isVMEnvironment,
   parseAnthropicToolCalls,
   parseGoogleToolCalls,
   parseOpenAIToolCalls,
   parseToolCalls,
+  resolveHostGateway,
+  rewriteLocalhostUrl,
   validateRoleplayTemplatePlugin,
   validateTemplateConfig
 });