[AI] Windows Copilot Runtime (Phi Silica) support

[mattleibow]

Summary

Stacked on top of #171. Migrates Windows Phi Silica (Copilot Runtime) support from dotnet/maui#33605 into maui-labs.

Changes

Library (src/AI/Microsoft.Maui.Essentials.AI)

• Add PhiSilicaChatClient, PhiSilicaExtensions, PhiSilicaModelFactory (verbatim copy)
• Add VersionOverride=2.0.0-experimental6 for Microsoft.WindowsAppSDK (AI projects only — does not affect other repo consumers)
• Add AppxOSMaxVersionTestedReplaceManifestVersion=false to prevent SDK from overriding the manifest's MaxVersionTested
• Update PublicAPI/net-windows/PublicAPI.Unshipped.txt with 7 new API entries

Sample

• Add AppContentIndexerSearchService (Windows semantic search via OS AppContentIndexer)
• Add PhiSilicaToolsAndSchemaClient (function-calling middleware for Phi Silica)
• Register AddPhiSilicaServices in MauiProgram.cs via #elif WINDOWS
• Update Windows Package.appxmanifest: systemAIModels capability + MaxVersionTested=10.0.26226.0

DeviceTests

• Add PhiSilicaChatClientTests and PhiSilicaExperimentTests (verbatim, [Category] stripped)
• Mark 3 base test methods virtual so Phi Silica subclass can override them
• Link PhiSilicaToolsAndSchemaClient from sample (file link, Windows only)
• Add SelfContained + WindowsAppSDKSelfContained for Windows to bundle experimental WinAppSDK into MSIX

Docs

• Move TOOL-CALLING-README.md to docs/ai/ (was in Platform/Windows in source)

Notes

• Microsoft.WindowsAppSDK 2.0.0-experimental6 is required for Microsoft.Windows.AI.Text.LanguageModel (Phi Silica WinRT API). The VersionOverride scopes this to AI projects only.
• Phi Silica requires Windows 10.0.26100.0 at runtime ([SupportedOSPlatform]); TFM stays at 19041 for build compat.
• After PR Add Microsoft.Maui.Essentials.AI — on-device AI for .NET MAUI #171 merges, GitHub will automatically retarget this PR to main.

[github-actions]

Expert Code Review — PR #178: Windows Copilot Runtime (Phi Silica) Support

Reviewed all changed files across the library, sample, and device tests. Below are the findings ordered by severity.

---

🔴 CRITICAL

1. DI crash on Windows: ISemanticSearchService resolution throws at runtime

• File: samples/Microsoft.Maui.Essentials.AI.Sample/MauiProgram.cs
• Line: 70–71
• Scenario: On Windows, AddPhiSilicaServices() registers ISemanticSearchService → AppContentIndexerSearchService (line 205). Then line 70 unconditionally overwrites it with a factory that resolves IEmbeddingGenerator<string, Embedding<float>> — which is never registered in the Windows path. The last registration wins in DI, so any consumer of ISemanticSearchService will throw InvalidOperationException at runtime.
• Recommendation: Wrap lines 69–71 in #if !WINDOWS (or move the registration into each platform method that actually registers an embedding generator), so on Windows only AppContentIndexerSearchService is used.

---

🟡 MODERATE

2. Negative TopK silently wraps to huge uint — unexpected model behavior

• File: src/AI/Microsoft.Maui.Essentials.AI/Platform/Windows/PhiSilicaChatClient.cs
• Line: 249
• Scenario: ChatOptions.TopK is int. If a consumer passes a negative value (e.g., -1 as sentinel), (uint)topK wraps to 4294967295, causing the model to behave unpredictably.
• Recommendation: Add a guard:

  if (topK < 0)
      throw new ArgumentOutOfRangeException(nameof(options), "TopK must be non-negative.");
  languageModelOptions.TopK = (uint)topK;

3. CancellationTokenRegistration not disposed — potential memory leak with long-lived tokens

• File: src/AI/Microsoft.Maui.Essentials.AI/Platform/Windows/PhiSilicaChatClient.cs
• Line: 122
• Scenario: cancellationToken.Register(...) returns a CancellationTokenRegistration. If the caller uses a long-lived or linked token, the registration (and its closure capturing operation) stays alive until the token is disposed. For short-lived per-request tokens this is fine; for singleton tokens it leaks.
• Recommendation: Capture the registration and dispose it after the enumeration completes:

  var ctr = cancellationToken.Register(() => operation.Cancel());
  try { await foreach (...) { yield return update; } }
  finally { ctr.Dispose(); }

4. Thread-unsafe Dictionary access in AppContentIndexerSearchService

• File: samples/Microsoft.Maui.Essentials.AI.Sample/Services/AppContentIndexerSearchService.cs
• Lines: 15–30, 34, 44
• Scenario: GetOrCreateIndexer reads/writes a plain Dictionary<string, AppContentIndexer> from multiple Task.Run callbacks concurrently (both IndexAsync and SearchAsync call it from pool threads). Concurrent access to Dictionary causes corruption or KeyNotFoundException.
• Recommendation: Use ConcurrentDictionary<string, AppContentIndexer> with GetOrAdd, or add a lock around the method.

5. PhiSilicaExtensions.AsIChatClient missing [SupportedOSPlatform] attribute

• File: src/AI/Microsoft.Maui.Essentials.AI/Platform/Windows/PhiSilicaExtensions.cs
• Lines: 10, 23
• Scenario: PhiSilicaChatClient is annotated with [SupportedOSPlatform("windows10.0.26100.0")], but the extension method AsIChatClient (and its class) has no such attribute. Consumers calling model.AsIChatClient() won't get platform compatibility warnings at their call-site.
• Recommendation: Add [SupportedOSPlatform("windows10.0.26100.0")] to the class or method.

---

🟢 MINOR

6. JsonDocument not disposed in BuildToolCallSchema

• File: samples/Microsoft.Maui.Essentials.AI.Sample/Services/PhiSilicaToolsAndSchemaClient.cs
• Lines: 271, 293
• Scenario: JsonDocument.Parse(json).RootElement.Clone() creates a JsonDocument that is never disposed. While .Clone() makes the element independent and the GC will clean up eventually, it pins pooled buffers until finalization.
• Recommendation: using var doc = JsonDocument.Parse(json); return doc.RootElement.Clone();

7. Potential empty-prompt edge case when options.Instructions is set but all messages have only non-text content

• File: src/AI/Microsoft.Maui.Essentials.AI/Platform/Windows/PhiSilicaChatClient.cs
• Lines: 78–82
• Scenario: When options.Instructions is provided, NormalizeChatMessages returns it as system prompt and keeps all messages (including system role messages) in history. If the only message is a system message (now used as both Instructions context and still in history), the ConvertToPrompt will include a System: ... prefix which may confuse the model since it's already in the context.
• Recommendation: When options.Instructions is set, consider filtering out the original system message from history if it duplicates the instructions, or document that Instructions takes precedence and system messages are preserved as-is.

8. Silent exception swallowing in tool enum extraction

• File: samples/Microsoft.Maui.Essentials.AI.Sample/Services/PhiSilicaToolsAndSchemaClient.cs
• Line: 206
• Scenario: catch { } silently swallows all exceptions from JSON parsing of tool schemas. If a tool schema is malformed, the user gets no diagnostic feedback.
• Recommendation: At minimum log a warning or Debug.Write so developers can troubleshoot schema issues.

---

Summary

Severity	Count
🔴 CRITICAL	1
🟡 MODERATE	4
🟢 MINOR	3

The critical DI issue (#1) will cause a runtime crash for any Windows user of the sample app when ISemanticSearchService is resolved. The moderate issues are correctness/safety concerns in the shipped library code. The minor issues are in sample code and represent best-practice gaps.

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• learn.microsoft.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "learn.microsoft.com"

See Network Configuration for more information.

Generated by Expert Code Review (auto) for issue #178 · ● 24.1M