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 strong cross-SDK consistency. Here's a summary of what was verified:

Changes and their cross-SDK status

Change	Node.js	Python	Go	.NET	Rust
isSchemaInternal → field markers	@internal JSDoc	# Internal: comment	// Internal: doc comment	internal C# modifier	#[doc(hidden)] attribute
isSchemaExperimental for struct fields	@experimental JSDoc	# Experimental: comment	// Experimental: doc comment	(already handled)	<div class="warning"> block
history.compact optional params	compact(params?: HistoryCompactRequest)	compact(params=None)	Compact(ctx, params ...*HistoryCompactRequest)	CompactAsync(request?=null)	compact() + compact_with_params(params)
SessionCompactionCompleteData.CustomInstructions	✅ regenerated	✅ regenerated	✅ regenerated	✅ regenerated	✅ regenerated
TotalPremiumRequests → internal + optional	✅ regenerated	✅ regenerated	✅ regenerated	✅ regenerated	#[doc(hidden)] + Option<f64>

Notes

• x-opaque-json → JsonElement (C# only): This is correctly C#-specific. Other languages already use idiomatic fallback types for opaque JSON (unknown in TypeScript, Any in Python, interface{}/json.RawMessage in Go, serde_json::Value in Rust) — no mirror changes needed.
• Rust compact_with_params: Rust's lack of optional/default parameters makes the two-method pattern (compact() + compact_with_params(params)) the right idiomatic approach, consistent with the rest of the Rust SDK's patterns.
• All generated files across all language SDKs appear to be regenerated from the same updated schema, so type and field changes are uniform.

No consistency gaps found.

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