C# SDK: re-land x-opaque-json → JsonElement mapping with object boundary at RPC params

[SteveSandersonMS]

What this PR does

1. Codegen: x-opaque-json → JsonElement (scripts/codegen/csharp.ts)

The runtime schema generator now stamps x-opaque-json: true on every field/type that legitimately holds free-form JSON (tool args, hook payloads, telemetry, form schemas, etc.) and rejects everything else at build time. The codegen consumes that marker:

• DTO fields with x-opaque-json: true → JsonElement / JsonElement? (was object?).
• All bare-object fallbacks removed from the codegen; reaching an unmappable shape is now a hard error.
• Hand-written types that round-trip opaque JSON (ToolInvocation.Arguments, hook in/out, related serialization plumbing in Session.cs, SessionFsProvider.cs, Client.cs) switched to JsonElement on the wire. New TestJsonContext for tests.

2. RPC-boundary special-case (the bit that made #1343 painful)

The reverted PR forced consumers to pass JsonElement for outbound RPC method parameters (e.g. Rpc.Tools.HandlePendingToolCallAsync(... JsonElement result, ...)). That's worse UX than the old object? surface: callers naturally hold a typed CLR value (string, dictionary, generated DTO) and don't want to serialize before each call.

Fixed by introducing an asymmetric boundary:

• Inbound opaque-JSON (events, hook inputs, tool args, generated event DTOs, DTO fields) stays JsonElement(?) — consumers can introspect the wire payload directly.

• Outbound opaque-JSON at top-level RPC method parameters now accepts object/object?. The codegen generates a call to a new helper:

  public static JsonElement? ToJsonElementForWire(object? value)

  which short-circuits if value is already a JsonElement, otherwise serializes the runtime type using SerializerOptionsForMessageFormatter (the chained source-gen JsonSerializerContexts the SDK uses for all JSON-RPC traffic). This matches pre-revert serialization exactly.

  DTO field types stay JsonElement(?) — the object only appears at the public RPC surface. A generated call site looks like:

  public async Task<HandlePendingToolCallResult> HandlePendingToolCallAsync(
      string requestId, object? result = null, string? error = null, ...)
  {
      var request = new HandlePendingToolCallRequest {
          ..., Result = CopilotClient.ToJsonElementForWire(result), ...
      };
      ...
  }

• ToolResultObject.ToolTelemetry reverted to IDictionary<string, object>? for the same reason (it's a consumer-constructed outbound type). Tests updated.

Validation

• dotnet build clean across net472 / net8.0 / net10.0.
• 98 (net8.0) + 91 (net472) unit tests pass; failures match baseline (4 ConnectionTokenTests rely on the test-harness proxy subprocess and aren't relevant to this change).
• TS / Python / Go / Rust codegens regenerate cleanly against the updated runtime schema.

Dependencies

This PR requires runtime changes to be merged first (or for the runtime's regenerated generated/*.schema.json to ship a copy). The branch already contains regenerated artifacts from the runtime PR's schema; once the runtime merges and re-emits, no codegen changes will be needed here.

[stephentoub]

You can avoid the need for the suppress messages by passing in a JsonTypeInfo instead of Type, e.g. value.GetType() => SerializerOptionsForMessageFormatter.GetTypeInfo(value.GetType())

[github-actions]

Cross-SDK Consistency Review ✅

This PR maintains good cross-SDK consistency. Here's a summary:

Changes propagated to all SDKs

The schema-level changes (regenerated from the same source) are applied consistently across Node.js, Python, Go, Rust, and .NET:

• compact method now accepts optional HistoryCompactRequest params (customInstructions) — updated in all SDKs
• SessionCompactionCompleteData gains customInstructions field — updated in all SDKs
• HistoryCompactRequest type added to all SDK generated types
• Comment/doc updates (overage → "additional usage", experimental markers) — consistent across SDKs

Language idiom differences (expected, not issues)

• Rust exposes the new parameter as a separate compact_with_params(params) method rather than making the existing compact() parameter optional — this is idiomatic Rust and intentional.

Primary .NET-specific change

The JsonElement ↔ object boundary refactoring is .NET-specific and doesn't have a cross-SDK equivalent (other SDKs use native JSON types like any, dict, serde_json::Value, map[string]any which already serve the same purpose without needing this distinction).

No consistency gaps identified.

Generated by SDK Consistency Review Agent for issue #1359 · ● 4.3M · ◷