@quilltap/plugin-utils 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [2.4.0] - 2026-08-19
+
+### Added
+
+- `collapseLeadingSystemMessages(messages)` — folds a run of consecutive leading `system` messages into one, joining the contents with a blank line. Arrays with fewer than two leading system messages come back untouched (same reference).
+- `OpenAICompatibleProvider` gained `acceptsRepeatedSystemMessages` (default `true`, so every existing subclass is byte-identical on the wire) and applies it through `applySystemMessagePolicy` in both the streaming and non-streaming body builds. A subclass pointing at a local runtime sets it `false`: the model's own chat template is what runs there, and the Qwen family — plus several Llama- and Gemma-derived templates — `raise_exception` on any system message after index 0, rejecting the whole request. Quilltap emits up to three leading system blocks so its cache breakpoints survive, so every non-opening turn against such a model failed outright. (Quilltap bug 82.)
+
 ## [2.3.0] - 2026-08-15
 
 ### Added

package/README.md

@@ -150,6 +150,37 @@ This gives you a complete `LLMProvider` implementation with:
 npm install openai
 ```
 
+### Profile Parameters
+
+A connection profile's `parameters` blob is free-form JSON, handed to the
+provider as `LLMParams.profileParameters`. A provider that never reads it drops
+every setting the user saved, in silence — so forwarding is opt-in but explicit,
+and always allow-listed:
+
+```typescript
+import { applyProfileParameters } from '@quilltap/plugin-utils';
+
+const MY_ALLOWLIST = ['top_k', 'min_p', 'reasoning_effort'] as const;
+
+applyProfileParameters(body, params, MY_ALLOWLIST, (key, value, callParams, target) => {
+  // Return the value to send, or `undefined` to omit the key.
+  // Write into `target` to send it under a different key entirely.
+  return value;
+});
+```
+
+`undefined`, `null` and the empty string omit the key — the empty string is what
+the schema-driven profile editor stores for "use the model default". Never
+spread the blob: `model`, `messages`, `stream`, `stream_options` and `tools`
+must stay unreachable from a profile.
+
+Subclasses of `OpenAICompatibleProvider` get this by declaring
+`profileParamAllowlist` (empty by default, so a subclass that declares nothing
+is byte-identical on the wire) and optionally overriding `normalizeProfileParam`;
+providers that implement `TextProvider` directly call the function themselves.
+The keys must match whatever the plugin's `getProviderOptionsSchema()` renders,
+or a field the editor draws goes nowhere.
+
 ### System Prompt Plugin Utilities
 
 Create system prompt plugins that provide character prompt templates from `.md` files:

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, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.mjs';
+export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, collapseLeadingSystemMessages, 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.3.0";
+declare const PLUGIN_UTILS_VERSION = "2.4.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, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, resolveRequestTimeoutMs } from './providers/index.js';
+export { DEFAULT_REQUEST_TIMEOUT_MS, OpenAICompatibleProvider, OpenAICompatibleProviderConfig, ProfileParamNormalizer, applyProfileParameters, buildRequestAbortSignal, buildSdkClientOptions, buildSdkRequestOptions, collapseLeadingSystemMessages, 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.3.0";
+declare const PLUGIN_UTILS_VERSION = "2.4.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(src_exports, {
   buildRequestAbortSignal: () => buildRequestAbortSignal,
   buildSdkClientOptions: () => buildSdkClientOptions,
   buildSdkRequestOptions: () => buildSdkRequestOptions,
+  collapseLeadingSystemMessages: () => collapseLeadingSystemMessages,
   convertFromAnthropicFormat: () => convertFromAnthropicFormat,
   convertFromGoogleFormat: () => convertFromGoogleFormat,
   convertOpenAIToAnthropicFormat: () => convertOpenAIToAnthropicFormat,
@@ -443,6 +444,21 @@ function applyProfileParameters(body, params, allowlist, normalize) {
   }
 }
 
+// src/providers/system-messages.ts
+function collapseLeadingSystemMessages(messages) {
+  let runLength = 0;
+  while (runLength < messages.length && messages[runLength].role === "system") {
+    runLength++;
+  }
+  if (runLength < 2) return messages;
+  const run = messages.slice(0, runLength);
+  const merged = {
+    ...run[0],
+    content: run.map((m) => m.content ?? "").filter((c) => c.length > 0).join("\n\n")
+  };
+  return [merged, ...messages.slice(runLength)];
+}
+
 // src/providers/openai-compatible.ts
 var DEFAULT_MAX_RETRIES = 2;
 var OpenAICompatibleProvider = class {
@@ -458,6 +474,18 @@ var OpenAICompatibleProvider = class {
     this.supportedMimeTypes = [];
     /** Web search is not supported */
     this.supportsWebSearch = false;
+    /**
+     * Whether the endpoint tolerates more than one leading `system` message.
+     *
+     * True for every hosted service — and so the default, which keeps the
+     * outbound bytes of OpenRouter, Z.AI and every other subclass exactly as they
+     * were. A subclass that points at a local runtime applying the *model's* chat
+     * template sets this false: several template families reject a system message
+     * anywhere but index 0, and Quilltap's context builder deliberately emits up
+     * to three of them so its cache breakpoints survive. See Bug 82 and
+     * {@link collapseLeadingSystemMessages}.
+     */
+    this.acceptsRepeatedSystemMessages = true;
     /**
      * Profile-parameter keys this provider forwards from
      * `LLMParams.profileParameters` onto the request body.
@@ -485,6 +513,14 @@ var OpenAICompatibleProvider = class {
     }
     this.logger = createPluginLogger(`${this.providerName}Provider`);
   }
+  /**
+   * Apply {@link acceptsRepeatedSystemMessages} to a mapped wire-message array.
+   * Called by both body builds so the streaming and non-streaming shapes cannot
+   * drift apart.
+   */
+  applySystemMessagePolicy(messages) {
+    return this.acceptsRepeatedSystemMessages ? messages : collapseLeadingSystemMessages(messages);
+  }
   /**
    * Collects attachment failures for messages with attachments.
    * Since attachments are not supported, all attachments are marked as failed.
@@ -613,7 +649,7 @@ var OpenAICompatibleProvider = class {
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
     const client = this.createClient(apiKey);
-    const messages = params.messages.filter((m) => {
+    const mappedMessages = params.messages.filter((m) => {
       if (m.role === "tool" && !m.toolCallId) return false;
       return true;
     }).map((m) => {
@@ -640,6 +676,7 @@ var OpenAICompatibleProvider = class {
         content: m.content
       };
     });
+    const messages = this.applySystemMessagePolicy(mappedMessages);
     const body = {
       model: params.model,
       messages,
@@ -692,7 +729,7 @@ var OpenAICompatibleProvider = class {
     this.validateApiKeyRequirement(apiKey);
     const attachmentResults = this.collectAttachmentFailures(params);
     const client = this.createClient(apiKey);
-    const messages = params.messages.filter((m) => {
+    const mappedMessages = params.messages.filter((m) => {
       if (m.role === "tool" && !m.toolCallId) return false;
       return true;
     }).map((m) => {
@@ -719,6 +756,7 @@ var OpenAICompatibleProvider = class {
         content: m.content
       };
     });
+    const messages = this.applySystemMessagePolicy(mappedMessages);
     const body = {
       model: params.model,
       messages,
@@ -1100,7 +1138,7 @@ function rewriteLocalhostUrl(url) {
 }
 
 // src/version.generated.ts
-var PLUGIN_UTILS_VERSION = "2.3.0";
+var PLUGIN_UTILS_VERSION = "2.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILTIN_TOOL_NAMES,
@@ -1116,6 +1154,7 @@ var PLUGIN_UTILS_VERSION = "2.3.0";
   buildRequestAbortSignal,
   buildSdkClientOptions,
   buildSdkRequestOptions,
+  collapseLeadingSystemMessages,
   convertFromAnthropicFormat,
   convertFromGoogleFormat,
   convertOpenAIToAnthropicFormat,