fix: harden Qwen spell tool semantics

Author: NeoXider

Assets/CoreAI.Demos/QwenDemo/QwenDemoShared.cs

@@ -78,9 +78,36 @@ public string HudLine()
     /// </summary>
     public static class LlmMeter
     {
-        /// <summary>Both Qwen demos require a native tool call instead of accepting a text-only answer.</summary>
+        /// <summary>Fallback used when a demo turn permits more than one tool.</summary>
         public static LlmToolChoiceMode ToolChoiceMode => LlmToolChoiceMode.RequireAny;
 
+        /// <summary>Builds the strict native-tool request used by the Qwen demos.</summary>
+        public static AiTaskRequest BuildTaskRequest(
+            string roleId,
+            string hint,
+            int maxOutputTokens,
+            IReadOnlyList<string> allowedToolNames)
+        {
+            string[] validToolNames = allowedToolNames?
+                .Where(name => !string.IsNullOrWhiteSpace(name))
+                .Select(name => name.Trim())
+                .Distinct(StringComparer.Ordinal)
+                .ToArray() ?? Array.Empty<string>();
+            string requiredTool = validToolNames.Length == 1 ? validToolNames[0] : null;
+
+            return new AiTaskRequest
+            {
+                RoleId = roleId,
+                Hint = hint,
+                MaxOutputTokens = maxOutputTokens,
+                CancellationScope = roleId,
+                ForcedToolMode = string.IsNullOrEmpty(requiredTool)
+                    ? ToolChoiceMode
+                    : LlmToolChoiceMode.RequireSpecific,
+                RequiredToolName = requiredTool ?? ""
+            };
+        }
+
         public static async Task<LlmRunResult> RunAsync(
             string roleId,
             string hint,
@@ -102,14 +129,7 @@ public static async Task<LlmRunResult> RunAsync(
 
             try
             {
-                AiTaskRequest task = new()
-                {
-                    RoleId = roleId,
-                    Hint = hint,
-                    MaxOutputTokens = maxOutputTokens,
-                    CancellationScope = roleId,
-                    ForcedToolMode = ToolChoiceMode
-                };
+                AiTaskRequest task = BuildTaskRequest(roleId, hint, maxOutputTokens, allowedToolNames);
 
                 await foreach (LlmStreamChunk ch in orchestrator.RunStreamingAsync(task, CancellationToken.None))
                 {

Assets/CoreAI.Demos/QwenDemo/README.md

@@ -20,15 +20,22 @@ Both scenes contain their own `CoreAILifetimeScope`, camera, light, and demo con
 
 The HUD reports first-token latency, total latency, token usage, and executed tool calls. The model chooses an action; C# remains authoritative over wish charges, mana, value clamps, and Unity object access.
 Both agents use `AgentMode.ToolsOnly`, disable chat history, and send
-`LlmToolChoiceMode.RequireAny` on every turn so a text-only response cannot count as a successful action.
+`LlmToolChoiceMode.RequireSpecific` with their single expected tool so CoreAI narrows the native tool
+contract and a text-only response cannot count as a successful action. Spellcraft also gives the compact
+0.8B model explicit RU/EN element aliases; for example, `мега молния` maps to `storm` power `3`.
 The demo accepts exactly one successful expected tool call per turn. Zero calls, multiple calls, an
 unexpected tool, or a failed tool is rejected instead of being displayed as a successful cast. The
 determinism button repeats this same real tool-call path; it does not infer a decision from assistant text.
 
+The release smoke also checks the actual tool arguments for the Russian element presets. The compact model
+must return `storm|3` for `мега молния`, `fire|2` for `стена огня`, `poison|1` for
+`ядовитый туман над врагом`, and `frost|2` for `заморозь их до костей`. Effects are not generated by the
+model: each supported element selects a predefined C# gameplay/VFX branch, and C# clamps power and mana.
+
 ## Verification
 
-- `QwenDemoScenesEditModeTests` checks scene composition, the `ToolsOnly`/`RequireAny` contract, the
-  exact-one validator, and compact HUD layout.
+- `QwenDemoScenesEditModeTests` checks scene composition, the `ToolsOnly`/`RequireSpecific` contract,
+  Russian lightning semantics, the exact-one validator, and compact HUD layout.
 - `QwenDemoSafetyPlayModeTests` checks that parallel native tool callbacks can apply exactly one side
   effect per model turn and that the guard resets for the next turn. EditMode tests cover the readiness
   lock fields and invalid tool-call outcomes without loading a model.

Assets/CoreAI.Demos/QwenDemo/SpellcraftDemo.cs

@@ -23,10 +23,17 @@ public sealed class SpellcraftDemo : MonoBehaviour
         private const string RoleId = "DemoMage";
 
         private const string SystemPrompt =
-            "You interpret spells for a wizard. The player describes a spell in their own words (any " +
-            "language, including Russian). Call cast_spell EXACTLY ONCE with the closest element " +
-            "(one of: fire, frost, storm, poison, arcane) and an integer power from 1 to 3 reflecting how " +
-            "strong the description sounds. After the call, reply with ONE short line naming the spell.";
+            "You classify a wizard's spell description and MUST call cast_spell exactly once. " +
+            "Never answer with element/power as text. Use these exact semantic mappings: " +
+            "fire = fire, flame, burn, огонь, пламя; " +
+            "frost = ice, freeze, cold, лёд, лед, мороз, заморозить; " +
+            "storm = lightning, thunder, storm, молния, гром, гроза; " +
+            "poison = poison, toxic, venom, яд, ядовитый, токсичный; " +
+            "arcane = arcane, magic, mana, магия, мана. " +
+            "Power is an integer: 1 weak, 2 strong, 3 huge or mega. " +
+            "Examples: 'мега молния' => cast_spell(element='storm', power=3); " +
+            "'стена огня' => cast_spell(element='fire', power=2); " +
+            "'заморозь их до костей' => cast_spell(element='frost', power=2).";
 
         private static readonly string[] Presets =
         {
@@ -91,8 +98,10 @@ private async void Start()
                 .WithoutChatHistory()
                 .WithTemperature(0f)
                 .WithTool(new DelegateLlmTool("cast_spell",
-                    "Cast a spell. element is one of fire, frost, storm, poison, arcane. power is 1 (weak) " +
-                    "to 3 (mighty). Choose the element and power that best fit the player's description.",
+                    "Required action. Call exactly once. element must be fire, frost, storm, poison, or " +
+                    "arcane. Russian молния/гром/гроза means storm; огонь/пламя means fire; " +
+                    "лёд/лед/мороз means frost; яд/ядовитый means poison; магия/мана means arcane. " +
+                    "power is 1 weak, 2 strong, or 3 huge/mega.",
                     new Func<string, int, string>(CastSpell)))
                 .Build();
 

Assets/CoreAiUnity/CHANGELOG.md

@@ -44,6 +44,11 @@ Unity host: **CoreAI.Source** build, EditMode / PlayMode tests, Editor menus, do
 
 ### Fixed
 
+- Qwen Spellcraft now requires its single `cast_spell` tool by name and gives the 0.8B model explicit
+  bilingual element aliases and examples, preventing Russian lightning prompts such as `мега молния`
+  from being classified as frost or returned as plain text.
+- Chat request and streaming timeouts now use real time, so pausing the game with `Time.timeScale = 0`
+  cannot leave an LLM request waiting forever.
 - Removed hard-coded readiness requests from the endpoint factory and the unreachable direct-`HttpClient`
   registry fallback, preventing normal startup and hot switching from applying different route policies.
 - Readiness rejects unsafe base URIs and redirects instead of accepting an unrelated handler or forwarding

Assets/CoreAiUnity/Runtime/Source/Features/Chat/CoreAiChatService.cs

@@ -170,7 +170,8 @@ public async System.Threading.Tasks.Task<string> SendMessageAsync(
                 if (timeoutSec > 0)
                 {
                     timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
-                    timerHandle = timeoutCts.CancelAfterSlim(TimeSpan.FromSeconds(timeoutSec));
+                    timerHandle = timeoutCts.CancelAfterSlim(
+                        TimeSpan.FromSeconds(timeoutSec), DelayType.Realtime);
                     effectiveCt = timeoutCts.Token;
                 }
 
@@ -239,7 +240,8 @@ public async IAsyncEnumerable<LlmStreamChunk> SendMessageStreamingAsync(
                 if (timeoutSec > 0)
                 {
                     timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
-                    timerHandle = timeoutCts.CancelAfterSlim(TimeSpan.FromSeconds(timeoutSec));
+                    timerHandle = timeoutCts.CancelAfterSlim(
+                        TimeSpan.FromSeconds(timeoutSec), DelayType.Realtime);
                     effectiveCt = timeoutCts.Token;
                 }
 
@@ -672,7 +674,8 @@ private async System.Threading.Tasks.Task<string> SendUserImageMessageAsync(
                 if (timeoutSec > 0)
                 {
                     timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
-                    timerHandle = timeoutCts.CancelAfterSlim(TimeSpan.FromSeconds(timeoutSec));
+                    timerHandle = timeoutCts.CancelAfterSlim(
+                        TimeSpan.FromSeconds(timeoutSec), DelayType.Realtime);
                     effectiveCt = timeoutCts.Token;
                 }
 

Assets/CoreAiUnity/Tests/EditMode/CoreAiChatServiceEditModeTests.cs

@@ -380,33 +380,41 @@ public async Task SendMessageAsync_NullResult_ReturnsEmptyString()
         [Timeout(20000)]
         public IEnumerator SendMessageAsync_TimeoutWhenOrchestratorBlocks_ThrowsLlmOperationTimeoutException()
         {
-            BlockUntilCancelledOrchestrator orchestrator = new();
-            StubSettings settings = new() { LlmRequestTimeoutSecondsOverride = 0.2f };
-            CoreAiChatService service = new(orchestrator, settings: settings);
+            float previousTimeScale = Time.timeScale;
+            Time.timeScale = 0f;
+            try
+            {
+                BlockUntilCancelledOrchestrator orchestrator = new();
+                StubSettings settings = new() { LlmRequestTimeoutSecondsOverride = 0.2f };
+                CoreAiChatService service = new(orchestrator, settings: settings);
 
-            Task task = service.SendMessageAsync("hi", "TestRole");
+                Task task = service.SendMessageAsync("hi", "TestRole");
 
-            float deadline = Time.realtimeSinceStartup + 15f;
-            while (!task.IsCompleted && Time.realtimeSinceStartup < deadline)
-            {
-                yield return null;
-            }
+                float deadline = Time.realtimeSinceStartup + 15f;
+                while (!task.IsCompleted && Time.realtimeSinceStartup < deadline)
+                {
+                    yield return null;
+                }
 
-            Assert.IsTrue(task.IsCompleted, "SendMessageAsync should complete once the timeout token fires.");
-            // LlmOperationTimeoutException inherits OperationCanceledException — async Task reports
-            // TaskStatus.Canceled (not Faulted) and task.Exception is null; unwrap via GetResult().
-            try
-            {
-                task.GetAwaiter().GetResult();
-                Assert.Fail("Expected LlmOperationTimeoutException after timeout.");
-            }
-            catch (LlmOperationTimeoutException ex)
-            {
-                Assert.That(ex.Message, Does.Contain("timed out"));
+                Assert.IsTrue(task.IsCompleted,
+                    "SendMessageAsync should complete in real time while the game is paused.");
+                try
+                {
+                    task.GetAwaiter().GetResult();
+                    Assert.Fail("Expected LlmOperationTimeoutException after timeout.");
+                }
+                catch (LlmOperationTimeoutException ex)
+                {
+                    Assert.That(ex.Message, Does.Contain("timed out"));
+                }
+                catch (Exception ex)
+                {
+                    Assert.Fail($"Expected LlmOperationTimeoutException, got {ex.GetType().Name}: {ex.Message}");
+                }
             }
-            catch (Exception ex)
+            finally
             {
-                Assert.Fail($"Expected LlmOperationTimeoutException, got {ex.GetType().Name}: {ex.Message}");
+                Time.timeScale = previousTimeScale;
             }
         }
 

Assets/CoreAiUnity/Tests/EditMode/CoreAiRoutingUiEditModeTests.cs

@@ -74,7 +74,14 @@ public void ChatApiSelector_AutomaticClearsPersistedAgentOverride()
 
                 panel.EnableApiSwitching();
                 DropdownField dropdown = header.Q<DropdownField>(className: "coreai-chat-api-dropdown");
-                dropdown.value = dropdown.choices[0];
+                string automaticLabel = dropdown.choices[0];
+                using (ChangeEvent<string> evt = ChangeEvent<string>.GetPooled(dropdown.value, automaticLabel))
+                {
+                    dropdown.SetValueWithoutNotify(automaticLabel);
+                    typeof(CoreAiChatPanel).GetMethod("OnApiProfileChanged",
+                            BindingFlags.Instance | BindingFlags.NonPublic)
+                        ?.Invoke(panel, new object[] { evt });
+                }
 
                 Assert.AreEqual(string.Empty, _controller.GetProfileForRole("SmartChat"));
                 Assert.AreEqual(string.Empty, panel.SelectedRoutingProfileId);
@@ -167,11 +174,14 @@ public void HubEndpointEditor_HidesSessionKeyClearOutsideHttpEndpoints()
             Button clearKey = FindButton(root, "Clear saved session key");
 
             Assert.AreEqual(DisplayStyle.Flex, clearKey.style.display.value);
-            kind.value = "LLMUnity";
+            kind.SetValueWithoutNotify("LLMUnity");
+            InvokePage(page, "RefreshEndpointEditorVisibility");
             Assert.AreEqual(DisplayStyle.None, clearKey.style.display.value);
-            kind.value = "Offline";
+            kind.SetValueWithoutNotify("Offline");
+            InvokePage(page, "RefreshEndpointEditorVisibility");
             Assert.AreEqual(DisplayStyle.None, clearKey.style.display.value);
-            kind.value = "HTTP API";
+            kind.SetValueWithoutNotify("HTTP API");
+            InvokePage(page, "RefreshEndpointEditorVisibility");
             Assert.AreEqual(DisplayStyle.Flex, clearKey.style.display.value);
             page.OnDestroyed();
         }

Assets/CoreAiUnity/Tests/EditMode/QwenDemoScenesEditModeTests.cs

@@ -24,6 +24,31 @@ public void QwenDemos_RequireNativeToolCalls()
             Type meter = Type.GetType("CoreAI.ExampleGame.QwenDemo.LlmMeter, CoreAI.Demos", true);
             object mode = meter.GetProperty("ToolChoiceMode")?.GetValue(null);
             Assert.AreEqual(LlmToolChoiceMode.RequireAny, mode);
+
+            MethodInfo build = meter.GetMethod("BuildTaskRequest");
+            AiTaskRequest request = (AiTaskRequest)build.Invoke(null,
+                new object[] { "DemoMage", "мега молния", 160, new[] { "cast_spell" } });
+            Assert.AreEqual(LlmToolChoiceMode.RequireSpecific, request.ForcedToolMode);
+            Assert.AreEqual("cast_spell", request.RequiredToolName);
+
+            AiTaskRequest multiToolRequest = (AiTaskRequest)build.Invoke(null,
+                new object[] { "Demo", "choose", 160, new[] { "first", "second" } });
+            Assert.AreEqual(LlmToolChoiceMode.RequireAny, multiToolRequest.ForcedToolMode);
+            Assert.AreEqual(string.Empty, multiToolRequest.RequiredToolName);
+        }
+
+        [Test]
+        public void SpellcraftPrompt_MapsRussianLightningToStorm()
+        {
+            Type spellcraft = Type.GetType(
+                "CoreAI.ExampleGame.QwenDemo.SpellcraftDemo, CoreAI.Demos", true);
+            FieldInfo promptField = spellcraft.GetField("SystemPrompt",
+                BindingFlags.Static | BindingFlags.NonPublic);
+            string prompt = (string)promptField.GetRawConstantValue();
+
+            StringAssert.Contains("молния, гром, гроза", prompt);
+            StringAssert.Contains("'мега молния' => cast_spell(element='storm', power=3)", prompt);
+            StringAssert.Contains("Never answer with element/power as text", prompt);
         }
 
         [TestCase(null, false)]

TODO.md

@@ -3,11 +3,12 @@
 > Updated 2026-07-15. Tracks open work by priority. Shipped work is in `CHANGELOG.md` (both packages);
 > non-blocking future work in `Assets/CoreAiUnity/Docs/BACKLOG.md`.
 > Released: 5.8.10 (2026-07-13, all five packages in lockstep). Unreleased packages are aligned at 5.9.0.
-> Last full verification 2026-07-15 in the interactive editor: CoreAI EditMode 1675 passed / 0 failed
-> (1645 host + 30 core/example), PlayMode `FastNoLlm` 73 passed / 0 failed, and six Unity-generated
-> `dotnet build` compile gates completed with 0 errors. Live Qwen3.5-0.8B LLMUnity smokes called
-> Genie `grant_gold` in 6481 ms and Spellcraft `cast_spell` in 6112 ms. Spellcraft determinism passed 5/5
-> as `storm|1` (0 errors, 6379 ms average); Hub/Chat started with 0 warnings/errors.
+> Last full verification 2026-07-15 in the interactive editor: EditMode 1691 passed / 0 failed /
+> 4 ignored optional Neoxider Pages tests, PlayMode `FastNoLlm` 73 passed / 0 failed, and six
+> Unity-generated `dotnet build` compile gates completed with 0 errors. Live Qwen3.5-0.8B LLMUnity
+> smokes called Genie `grant_gold`; Spellcraft classified `мега молния` as `storm|3`, `стена огня`
+> as `fire|2`, `ядовитый туман` as `poison|1`, and `заморозь их до костей` as `frost|2`, each through
+> native `cast_spell` with no ToolsOnly error. Hub/Chat started with 0 warnings/errors.
 
 ## [A6] Deep audit wave (2026-07-13) — runtime / architecture / tests / security, all 22 findings fixed
 
@@ -116,6 +117,9 @@
       `/v1/chat/completions` connection probe, and
       reject any result other than exactly one successful expected tool call. EditMode and no-model PlayMode
       regressions cover the contract.
+- [x] Qwen Spellcraft single-tool turns use `RequireSpecific(cast_spell)` and an explicit bilingual
+      element contract; all four Russian element presets have regression coverage and passed live-model
+      smoke on the compact 0.8B model.
 - [x] Deterministic startup smoke for all ten published scenes (including Skills and
       LiveMechanicsModsChat): no missing scripts, scope/camera present, supported shaders, no
       unexpected startup errors. Fixed missing Mods scopes, Mirror remnants, Hub wiring, and Wave URP color.