@quilltap/plugin-utils 2.2.19 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [2.3.0] - 2026-08-15
+
+### Added
+
+- `applyProfileParameters(body, params, allowlist, normalize?)` — the one mechanism providers use to forward a connection profile's free-form `parameters` blob onto a request body. Allow-listed (never spread, so `model` / `messages` / `stream` / `tools` stay unreachable from a profile); `undefined`, `null` and the empty string omit the key. Exported as a free function rather than a base-class method because only one plugin extends `OpenAICompatibleProvider` — Z.AI, OpenRouter and Ollama implement their providers directly and reach it by composition.
+- `OpenAICompatibleProvider` gained `profileParamAllowlist` (empty by default, so every existing subclass is byte-identical on the wire until it opts in) and an overridable `normalizeProfileParam`, applied in both the streaming and non-streaming body builds.
+- `OpenAICompatibleProvider` now sends `tools` / `tool_choice` when the caller supplies tools, and parses `tool_calls` back — from `choice.message.tool_calls` on the non-streaming path, and by accumulating index-keyed `delta.tool_calls` fragments while streaming. Previously it could never call a tool.
+
 ## [2.2.19] - 2026-08-03
 
 ### Fixed

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 export { AnthropicToolDefinition, CharacterPluginDataEntry, CharacterPluginDataMap, GoogleToolDefinition, LogContext, LogLevel, OpenAIToolDefinition, PluginLogger, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool, createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';
 export { T as ToolCallFormat, a as ToolConvertTarget, b as applyDescriptionLimit, c as convertFromAnthropicFormat, d as convertFromGoogleFormat, e as convertOpenAIToAnthropicFormat, f as convertOpenAIToGoogleFormat, g as convertToAnthropicFormat, h as convertToGoogleFormat, i as convertToolTo, j as convertToolsTo, k as detectToolCallFormat, l as hasToolCalls, p as parseAnthropicToolCalls, m as parseGoogleToolCalls, n as parseOpenAIToolCalls, o as parseToolCalls } from './converters-BPYo8xdH.mjs';
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.mjs';
-export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.mjs';
+export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.mjs';
 export { CreateSystemPromptPluginOptions, createSystemPromptPlugin, validateSystemPromptPlugin } from './system-prompts/index.mjs';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.mjs';
 import 'openai';
@@ -124,6 +124,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "2.2.19";
+declare const PLUGIN_UTILS_VERSION = "2.3.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AnthropicToolDefinition, CharacterPluginDataEntry, CharacterPluginDataMap, GoogleToolDefinition, LogContext, LogLevel, OpenAIToolDefinition, PluginLogger, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool, createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';
 export { T as ToolCallFormat, a as ToolConvertTarget, b as applyDescriptionLimit, c as convertFromAnthropicFormat, d as convertFromGoogleFormat, e as convertOpenAIToAnthropicFormat, f as convertOpenAIToGoogleFormat, g as convertToAnthropicFormat, h as convertToGoogleFormat, i as convertToolTo, j as convertToolsTo, k as detectToolCallFormat, l as hasToolCalls, p as parseAnthropicToolCalls, m as parseGoogleToolCalls, n as parseOpenAIToolCalls, o as parseToolCalls } from './converters-BPYo8xdH.js';
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.js';
-export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.js';
+export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.js';
 export { CreateSystemPromptPluginOptions, createSystemPromptPlugin, validateSystemPromptPlugin } from './system-prompts/index.js';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.js';
 import 'openai';
@@ -124,6 +124,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "2.2.19";
+declare const PLUGIN_UTILS_VERSION = "2.3.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.js

@@ -39,6 +39,7 @@ __export(src_exports, {
   __injectCoreLoggerFactory: () => __injectCoreLoggerFactory,
   __injectQuilltapVersion: () => __injectQuilltapVersion,
   applyDescriptionLimit: () => applyDescriptionLimit,
+  applyProfileParameters: () => applyProfileParameters,
   buildRequestAbortSignal: () => buildRequestAbortSignal,
   buildSdkClientOptions: () => buildSdkClientOptions,
   buildSdkRequestOptions: () => buildSdkRequestOptions,
@@ -427,6 +428,21 @@ function buildRequestAbortSignal(params, defaultMs = DEFAULT_REQUEST_TIMEOUT_MS)
   return AbortSignal.timeout(resolveRequestTimeoutMs(params, defaultMs));
 }
 
+// src/providers/profile-parameters.ts
+function applyProfileParameters(body, params, allowlist, normalize) {
+  const profile = params.profileParameters;
+  if (!profile || typeof profile !== "object") return;
+  const bag = profile;
+  for (const key of allowlist) {
+    const raw = bag[key];
+    if (raw === void 0 || raw === null) continue;
+    if (typeof raw === "string" && raw === "") continue;
+    const value = normalize ? normalize(key, raw, params, body) : raw;
+    if (value === void 0) continue;
+    body[key] = value;
+  }
+}
+
 // src/providers/openai-compatible.ts
 var DEFAULT_MAX_RETRIES = 2;
 var OpenAICompatibleProvider = class {
@@ -442,6 +458,16 @@ var OpenAICompatibleProvider = class {
     this.supportedMimeTypes = [];
     /** Web search is not supported */
     this.supportsWebSearch = false;
+    /**
+     * Profile-parameter keys this provider forwards from
+     * `LLMParams.profileParameters` onto the request body.
+     *
+     * **Empty by default**, so a subclass that declares nothing sends exactly the
+     * bytes it sent before this mechanism existed. Subclasses opt in by
+     * overriding with their own allow-list; `model`, `messages`, `stream`,
+     * `stream_options` and `tools` must never appear in one.
+     */
+    this.profileParamAllowlist = [];
     if (typeof config === "string") {
       this.baseUrl = config;
       this.providerName = "OpenAICompatible";
@@ -529,6 +555,53 @@ var OpenAICompatibleProvider = class {
   buildRequestOptions(params) {
     return buildSdkRequestOptions(params);
   }
+  /**
+   * Per-key hook for allow-listed profile parameters. The default forwards the
+   * stored value verbatim.
+   *
+   * Override to reshape a value (the editor stores flat strings where some APIs
+   * want objects), to gate a key on the model, or — by writing into `body` and
+   * returning `undefined` — to send it under a different key entirely.
+   */
+  normalizeProfileParam(_key, value, _params, _body) {
+    return value;
+  }
+  /**
+   * Apply {@link profileParamAllowlist} to a request body under construction.
+   * Called by both body builds so the streaming and non-streaming shapes cannot
+   * drift apart.
+   */
+  applyProfileParams(body, params) {
+    applyProfileParameters(
+      body,
+      params,
+      this.profileParamAllowlist,
+      (key, value, callParams, target) => this.normalizeProfileParam(key, value, callParams, target)
+    );
+  }
+  /**
+   * Normalize an OpenAI-shaped `tool_calls` array into Quilltap's `ToolCall`
+   * shape, tolerating servers that hand back already-parsed argument objects
+   * where the OpenAI wire format specifies a JSON string.
+   */
+  normalizeToolCalls(toolCalls) {
+    if (!toolCalls || toolCalls.length === 0) return [];
+    const out = [];
+    for (const raw of toolCalls) {
+      const tc = raw;
+      if (!tc?.function?.name) continue;
+      const args = tc.function.arguments;
+      out.push({
+        id: tc.id ?? "",
+        type: "function",
+        function: {
+          name: tc.function.name,
+          arguments: typeof args === "string" ? args : JSON.stringify(args ?? {})
+        }
+      });
+    }
+    return out;
+  }
   /**
    * Sends a message and returns the complete response.
    *
@@ -567,17 +640,26 @@ var OpenAICompatibleProvider = class {
         content: m.content
       };
     });
+    const body = {
+      model: params.model,
+      messages,
+      temperature: params.temperature ?? 0.7,
+      max_tokens: params.maxTokens ?? 4096,
+      top_p: params.topP ?? 1,
+      stop: params.stop,
+      ...params.cacheKey ? { user: params.cacheKey } : {},
+      // Tools arrive only once the runtime gate (the profile's "Allow tool
+      // use") has passed, so no separate guard is needed here.
+      ...params.tools && params.tools.length > 0 ? { tools: params.tools, tool_choice: params.toolChoice ?? "auto" } : {}
+    };
+    this.applyProfileParams(body, params);
     try {
-      const response = await client.chat.completions.create({
-        model: params.model,
-        messages,
-        temperature: params.temperature ?? 0.7,
-        max_tokens: params.maxTokens ?? 4096,
-        top_p: params.topP ?? 1,
-        stop: params.stop,
-        ...params.cacheKey ? { user: params.cacheKey } : {}
-      }, this.buildRequestOptions(params));
+      const response = await client.chat.completions.create(
+        body,
+        this.buildRequestOptions(params)
+      );
       const choice = response.choices[0];
+      const toolCalls = this.normalizeToolCalls(choice.message.tool_calls);
       return {
         content: choice.message.content ?? "",
         finishReason: choice.finish_reason,
@@ -587,7 +669,8 @@ var OpenAICompatibleProvider = class {
           totalTokens: response.usage?.total_tokens ?? 0
         },
         raw: response,
-        attachmentResults
+        attachmentResults,
+        ...toolCalls.length > 0 ? { toolCalls } : {}
       };
     } catch (error) {
       this.logger.error(
@@ -636,23 +719,32 @@ var OpenAICompatibleProvider = class {
         content: m.content
       };
     });
+    const body = {
+      model: params.model,
+      messages,
+      temperature: params.temperature ?? 0.7,
+      max_tokens: params.maxTokens ?? 4096,
+      top_p: params.topP ?? 1,
+      stop: params.stop,
+      stream: true,
+      stream_options: { include_usage: true },
+      ...params.cacheKey ? { user: params.cacheKey } : {},
+      ...params.tools && params.tools.length > 0 ? { tools: params.tools, tool_choice: params.toolChoice ?? "auto" } : {}
+    };
+    this.applyProfileParams(body, params);
     try {
-      const stream = await client.chat.completions.create({
-        model: params.model,
-        messages,
-        temperature: params.temperature ?? 0.7,
-        max_tokens: params.maxTokens ?? 4096,
-        top_p: params.topP ?? 1,
-        stop: params.stop,
-        stream: true,
-        stream_options: { include_usage: true },
-        ...params.cacheKey ? { user: params.cacheKey } : {}
-      }, this.buildRequestOptions(params));
+      const stream = await client.chat.completions.create(
+        body,
+        this.buildRequestOptions(params)
+      );
       let chunkCount = 0;
       let accumulatedUsage = null;
+      const toolCallAccumulator = /* @__PURE__ */ new Map();
+      let finishReason = null;
       for await (const chunk of stream) {
         chunkCount++;
-        const content = chunk.choices[0]?.delta?.content;
+        const choice = chunk.choices[0];
+        const content = choice?.delta?.content;
         const hasUsage = chunk.usage;
         if (hasUsage) {
           accumulatedUsage = {
@@ -661,6 +753,17 @@ var OpenAICompatibleProvider = class {
             total_tokens: chunk.usage?.total_tokens
           };
         }
+        if (choice?.delta?.tool_calls) {
+          for (const tcDelta of choice.delta.tool_calls) {
+            const idx = tcDelta.index ?? 0;
+            const existing = toolCallAccumulator.get(idx) ?? { id: "", name: "", arguments: "" };
+            if (tcDelta.id) existing.id = tcDelta.id;
+            if (tcDelta.function?.name) existing.name = tcDelta.function.name;
+            if (tcDelta.function?.arguments) existing.arguments += tcDelta.function.arguments;
+            toolCallAccumulator.set(idx, existing);
+          }
+        }
+        if (choice?.finish_reason) finishReason = choice.finish_reason;
         if (content) {
           yield {
             content,
@@ -668,6 +771,11 @@ var OpenAICompatibleProvider = class {
           };
         }
       }
+      const toolCalls = Array.from(toolCallAccumulator.values()).filter((tc) => tc.name).map((tc) => ({
+        id: tc.id,
+        type: "function",
+        function: { name: tc.name, arguments: tc.arguments }
+      }));
       yield {
         content: "",
         done: true,
@@ -676,7 +784,22 @@ var OpenAICompatibleProvider = class {
           completionTokens: accumulatedUsage.completion_tokens ?? 0,
           totalTokens: accumulatedUsage.total_tokens ?? 0
         } : void 0,
-        attachmentResults
+        attachmentResults,
+        // Only synthesized when the stream actually carried tool calls: the
+        // host's tool detection reads `rawResponse`, and an empty one on every
+        // ordinary turn would be noise in the logs for no gain.
+        ...toolCalls.length > 0 ? {
+          toolCalls,
+          rawResponse: {
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "", tool_calls: toolCalls },
+                finish_reason: finishReason
+              }
+            ]
+          }
+        } : {}
       };
     } catch (error) {
       this.logger.error(
@@ -977,7 +1100,7 @@ function rewriteLocalhostUrl(url) {
 }
 
 // src/version.generated.ts
-var PLUGIN_UTILS_VERSION = "2.2.19";
+var PLUGIN_UTILS_VERSION = "2.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILTIN_TOOL_NAMES,
@@ -989,6 +1112,7 @@ var PLUGIN_UTILS_VERSION = "2.2.19";
   __injectCoreLoggerFactory,
   __injectQuilltapVersion,
   applyDescriptionLimit,
+  applyProfileParameters,
   buildRequestAbortSignal,
   buildSdkClientOptions,
   buildSdkRequestOptions,