Fix structured-output parser and grammar regressions (#421)

* fix: recover structured output format correctness

* style: format template integration coverage

* fix: reject duplicate optional tool arguments

* fix: compile zero-argument Kimi grammars

* fix: close structured streaming and schema gaps

* fix: require canonical tool attribute encoding

* fix: bind structured schemas to exact tool routes

* fix: reject malformed structured route metadata

* fix: harden specialized grammar generation

* fix: reject empty specialized tool identities

* fix: defer disabled specialized schema validation

* fix: reconcile structured output recovery coverage

* style: match CI formatter

* fix: complete donor structured output reconciliation

* fix: preserve optional schema argument order parity

* fix: bound optional grammar state expansion

* fix: reject duplicate MiniMax JSON keys

* fix: close structured stream delimiter gaps

* fix: align GLM marker parsing with grammar

* fix: preserve GLM marker-like content

Author: leehack

AGENTS.md

@@ -41,6 +41,13 @@ For docs and release-sensitive snippets:
 dart run tool/testing/verify_release_docs_versions.dart
 ```
 
+For chat-template handler, parser, or grammar changes, run the pinned upstream
+suite plus compiled specialized-grammar acceptance checks:
+
+```bash
+tool/testing/run_template_parity_suites.sh
+```
+
 For coverage when `lib/` behavior changes or coverage is in doubt:
 
 ```bash

CHANGELOG.md

@@ -1,5 +1,24 @@
 ## Unreleased
 
+* Fixed DeepSeek V3.2 DSML tool calls using their upstream
+  `<｜DSML｜function_calls>` envelope while preserving DeepSeek V4's distinct
+  `<｜DSML｜tool_calls>` grammar and parser behavior.
+
+* Fixed partial GLM 4.5, Poolside Laguna, and Muse Glimmer tool envelopes
+  leaking into streamed assistant content, while preserving completed calls,
+  malformed final output, and ordinary text surrounding Muse recipient
+  channels.
+
+* Fixed schema-constrained tool calls for Kimi K3, MiniMax M1/M3, DeepSeek
+  V3.2/V4, and Muse Glimmer, including exact escaped names, required fields,
+  declared value types, matching MiniMax M3 element tags, zero-argument calls,
+  and strings containing delimiter characters. Required-tool mode now accepts
+  each format's reasoning/content prefix while still requiring a call.
+  MiniMax M3, DeepSeek DSML, Muse Glimmer, Poolside Laguna, and GLM 4.5 now
+  reconstruct argument values from the declared tool schema instead of
+  guessing from text. Added `ToolParam.nullType` for null-only JSON Schema
+  properties.
+
 * llama.cpp backend initialization failures now complete the worker startup
   handshake with a typed `LlamaBackendInitializationException` and collected
   native-loader diagnostics. A failed or incompatible worker is torn down

lib/llamadart.dart

@@ -94,7 +94,7 @@ export 'src/core/models/chat/completion_chunk.dart';
 
 // Tools
 export 'src/core/models/tools/tool_definition.dart';
-export 'src/core/models/tools/tool_param.dart';
+export 'src/core/models/tools/tool_param.dart' show ToolParam;
 export 'src/core/models/tools/tool_params.dart';
 
 // Models - Config

lib/src/core/engine/chat_completion_stream_parser.dart

@@ -3,6 +3,8 @@ import 'dart:async';
 import '../llama_logger.dart';
 import '../models/chat/chat_template_result.dart';
 import '../models/chat/completion_chunk.dart';
+import '../models/tools/tool_definition.dart';
+import '../template/chat_format.dart';
 import '../template/chat_template_engine.dart';
 
 enum _ToolStreamingMode { undecided, raw, parsed }
@@ -42,6 +44,7 @@ class ChatCompletionStreamParser {
     required bool enableThinking,
     required String modelName,
     required String completionId,
+    List<ToolDefinition>? tools,
   }) async* {
     final buffer = StringBuffer();
     var streamedContent = '';
@@ -58,7 +61,9 @@ class ChatCompletionStreamParser {
     // A forced-open thought can transition straight into a tool envelope
     // without producing `</think>`. Start in parsed mode so that envelope is
     // never streamed as reasoning before the final structured parse.
-    var streamingMode = templateResult.thinkingForcedOpen
+    var streamingMode =
+        templateResult.thinkingForcedOpen ||
+            _mayEmbedToolEnvelopeAfterContent(templateResult.format)
         ? _ToolStreamingMode.parsed
         : _ToolStreamingMode.undecided;
     var undecidedPrefix = '';
@@ -167,6 +172,7 @@ class ChatCompletionStreamParser {
             parseToolCalls: true,
             thinkingForcedOpen: templateResult.thinkingForcedOpen,
             parser: templateResult.parser,
+            tools: tools,
           );
 
           final partialReasoning = partialParsed.reasoningContent ?? '';
@@ -286,6 +292,7 @@ class ChatCompletionStreamParser {
       parseToolCalls: parseToolCallsEnabled,
       thinkingForcedOpen: templateResult.thinkingForcedOpen,
       parser: templateResult.parser,
+      tools: tools,
     );
 
     if (parseToolCallsEnabled) {
@@ -412,6 +419,16 @@ class ChatCompletionStreamParser {
     return false;
   }
 
+  static bool _mayEmbedToolEnvelopeAfterContent(int formatIndex) =>
+      formatIndex == ChatFormat.kimiK3.index ||
+      formatIndex == ChatFormat.minimaxM1.index ||
+      formatIndex == ChatFormat.minimaxM3.index ||
+      formatIndex == ChatFormat.deepseekV32.index ||
+      formatIndex == ChatFormat.deepseekV4.index ||
+      formatIndex == ChatFormat.museGlimmer.index ||
+      formatIndex == ChatFormat.glm45.index ||
+      formatIndex == ChatFormat.laguna.index;
+
   static int? _firstNonWhitespaceIndex(String value) {
     for (var i = 0; i < value.length; i++) {
       if (!_isWhitespaceCodeUnit(value.codeUnitAt(i))) {

lib/src/core/engine/engine.dart

@@ -686,6 +686,7 @@ class LlamaEngine {
       enableThinking: enableThinking,
       modelName: _modelPath ?? 'llama_model',
       completionId: completionId,
+      tools: effectiveTools,
     );
   }
 

lib/src/core/models/tools/tool_param.dart

@@ -5,6 +5,7 @@
 /// - [ToolParam.integer] for integer parameters
 /// - [ToolParam.number] for floating-point parameters
 /// - [ToolParam.boolean] for boolean parameters
+/// - [ToolParam.nullType] for parameters whose only valid value is `null`
 /// - [ToolParam.enumType] for enum parameters with allowed values
 /// - [ToolParam.array] for array parameters
 /// - [ToolParam.object] for nested object parameters
@@ -52,6 +53,13 @@ sealed class ToolParam {
     bool required = false,
   }) => _BooleanParam(name: name, description: description, required: required);
 
+  /// Creates a parameter whose only valid JSON value is `null`.
+  static ToolParam nullType(
+    String name, {
+    String? description,
+    bool required = false,
+  }) => _NullParam(name: name, description: description, required: required);
+
   /// Creates an enum parameter with a list of allowed values.
   static ToolParam enumType(
     String name, {
@@ -95,6 +103,47 @@ sealed class ToolParam {
   Map<String, dynamic> toJsonSchema();
 }
 
+/// Returns an actionable identity error for [parameters], or `null` when every
+/// object property name is non-empty and unique within its containing object.
+///
+/// Array item names are not represented in JSON Schema and are therefore not
+/// validated, but object properties nested inside array items are.
+String? toolParamIdentityError(
+  List<ToolParam> parameters, {
+  required String path,
+}) {
+  final names = <String>{};
+  for (final parameter in parameters) {
+    if (parameter.name.isEmpty) {
+      return 'Structured tool schemas require non-empty parameter names at '
+          '$path.';
+    }
+    if (!names.add(parameter.name)) {
+      return 'Structured tool schemas require unique parameter names at '
+          '$path; "${parameter.name}" is declared more than once.';
+    }
+  }
+
+  for (final parameter in parameters) {
+    final nestedPath = '$path.${parameter.name}';
+    final error = _nestedToolParamIdentityError(parameter, nestedPath);
+    if (error != null) {
+      return error;
+    }
+  }
+  return null;
+}
+
+String? _nestedToolParamIdentityError(ToolParam parameter, String path) {
+  if (parameter is _ObjectParam) {
+    return toolParamIdentityError(parameter.properties, path: path);
+  }
+  if (parameter is _ArrayParam) {
+    return _nestedToolParamIdentityError(parameter.itemType, '$path[]');
+  }
+  return null;
+}
+
 final class _StringParam extends ToolParam {
   const _StringParam({required super.name, super.description, super.required})
     : super._();
@@ -139,6 +188,17 @@ final class _BooleanParam extends ToolParam {
   };
 }
 
+final class _NullParam extends ToolParam {
+  const _NullParam({required super.name, super.description, super.required})
+    : super._();
+
+  @override
+  Map<String, dynamic> toJsonSchema() => {
+    'type': 'null',
+    if (description != null) 'description': description,
+  };
+}
+
 final class _EnumParam extends ToolParam {
   final List<String> values;
 

lib/src/core/template/chat_format.dart

@@ -133,14 +133,19 @@ enum ChatFormat {
   /// MiniMax M3 — namespaced XML invokes with `<mm:think>` reasoning.
   minimaxM3,
 
-  /// DeepSeek V3.2/V4 — DSML invokes with typed parameter values.
+  /// DeepSeek V4 — DSML `tool_calls` with typed parameter values.
   deepseekV4,
 
   /// Muse Glimmer — recipient channels with ATEM function-call markup.
   museGlimmer,
 
   /// Poolside Laguna — tagged reasoning and arg-key/value tool calls.
   laguna,
+
+  /// DeepSeek V3.2 — DSML `function_calls` with typed parameter values.
+  ///
+  /// Appended to preserve the serialized indices of existing formats.
+  deepseekV32,
 }
 
 /// Detects the [ChatFormat] by scanning a Jinja template source string
@@ -179,8 +184,12 @@ ChatFormat detectChatFormat(String? templateSource) {
   // variable, so detecting only literal rendered tags misses every variant.
   if (templateSource.contains('dsml_token') &&
       templateSource.contains('DSML') &&
-      (templateSource.contains('function_calls') ||
-          templateSource.contains('tool_calls'))) {
+      templateSource.contains('function_calls')) {
+    return ChatFormat.deepseekV32;
+  }
+  if (templateSource.contains('dsml_token') &&
+      templateSource.contains('DSML') &&
+      templateSource.contains('tool_calls')) {
     return ChatFormat.deepseekV4;
   }
 

lib/src/core/template/chat_template_engine.dart

@@ -413,7 +413,7 @@ class ChatTemplateEngine {
     LlamaChatTemplateResult result,
     ToolChoice toolChoice,
   ) {
-    if (toolChoice != ToolChoice.required || !result.grammarLazy) {
+    if (toolChoice != ToolChoice.required) {
       return result;
     }
     if (result.grammar == null || result.grammar!.isEmpty) {
@@ -423,7 +423,8 @@ class ChatTemplateEngine {
     final resultFormat = result.format < ChatFormat.values.length
         ? ChatFormat.values[result.format]
         : ChatFormat.generic;
-    if (_requiredKeepsLazyFormats.contains(resultFormat)) {
+    if (_requiredKeepsLazyFormats.contains(resultFormat) &&
+        result.grammarLazy) {
       return result;
     }
 
@@ -434,7 +435,7 @@ class ChatTemplateEngine {
       grammarLazy: false,
       additionalStops: result.additionalStops,
       preservedTokens: result.preservedTokens,
-      grammarTriggers: result.grammarTriggers,
+      grammarTriggers: const [],
       thinkingForcedOpen: result.thinkingForcedOpen,
       parser: result.parser,
       tokenCount: result.tokenCount,
@@ -444,13 +445,16 @@ class ChatTemplateEngine {
   /// Parses raw LLM output using the format's handler.
   ///
   /// The [formatIndex] should come from [LlamaChatTemplateResult.format].
+  /// [tools] supplies the schemas needed by formats whose wire representation
+  /// does not encode enough type information to reconstruct arguments safely.
   static ChatParseResult parse(
     int formatIndex,
     String output, {
     bool isPartial = false,
     bool parseToolCalls = true,
     bool thinkingForcedOpen = false,
     String? parser,
+    List<ToolDefinition>? tools,
   }) {
     final resolved = _resolveHandlerForParse(formatIndex: formatIndex);
     final handler = resolved.handler;
@@ -482,6 +486,16 @@ class ChatTemplateEngine {
       );
     }
 
+    if (handler is ToolSchemaAwareChatTemplateHandler) {
+      return (handler as ToolSchemaAwareChatTemplateHandler).parseWithTools(
+        output,
+        tools: tools,
+        isPartial: isPartial,
+        parseToolCalls: parseToolCalls,
+        thinkingForcedOpen: thinkingForcedOpen,
+      );
+    }
+
     return handler.parse(
       output,
       isPartial: isPartial,
@@ -557,6 +571,8 @@ class ChatTemplateEngine {
         return MinimaxM3Handler();
       case ChatFormat.deepseekV4:
         return DeepseekV4Handler();
+      case ChatFormat.deepseekV32:
+        return DeepseekV32Handler();
       case ChatFormat.museGlimmer:
         return MuseGlimmerHandler();
       case ChatFormat.laguna:

lib/src/core/template/chat_template_handler.dart

@@ -236,3 +236,20 @@ abstract class ChatTemplateHandler {
     return DateTime.now();
   }
 }
+
+/// Optional handler contract for output formats whose argument decoding depends
+/// on the tool JSON schemas supplied for the completion request.
+///
+/// [ChatTemplateEngine] uses this contract when schemas are available while
+/// retaining [ChatTemplateHandler.parse] for callers that only have raw output.
+abstract interface class ToolSchemaAwareChatTemplateHandler {
+  /// Parses [output] using [tools] to validate names, required properties, and
+  /// schema-directed argument types.
+  ChatParseResult parseWithTools(
+    String output, {
+    List<ToolDefinition>? tools,
+    bool isPartial = false,
+    bool parseToolCalls = true,
+    bool thinkingForcedOpen = false,
+  });
+}