Add $ref support to all four language code generators

[stephentoub]

Summary

Enable JSON Schema $ref for type deduplication across all SDK code generators (TypeScript, Python, Go, C#). This allows the runtime to declare a shared type once using $ref and have each generator produce a single deduplicated type per language.

Changes

scripts/codegen/utils.ts

• Add resolveRef(), refTypeName(), collectDefinitions() helpers
• Normalize $defs to definitions in postProcessSchema for cross-draft compatibility
• Add definitions/$defs fields to ApiSchema interface

scripts/codegen/typescript.ts

• Build a single combined schema with shared definitions and compile once via unreachableDefinitions, instead of per-method compilation
• Preserves @experimental JSDoc annotations via post-processing

scripts/codegen/python.ts

• Include all definitions alongside SessionEvent for quicktype $ref resolution
• Include shared API definitions in each RPC addSource call

scripts/codegen/go.ts

• Add $ref handling to the custom Go session events generator (resolveGoPropertyType) with definitions on GoCodegenCtx
• Include shared API definitions in RPC combined schema for quicktype $ref resolution

scripts/codegen/csharp.ts

• Add $ref handling to resolveSessionPropertyType and resolveRpcType
• Generate classes for referenced types on demand using module-level sessionDefinitions/rpcDefinitions state
• Handle $ref in array items

Motivation

The copilot-agent-runtime is moving to use $ref for type deduplication in tool schemas. Without this change, generators would either fail to resolve $ref pointers or inline duplicate type definitions.

[Copilot]

Pull request overview

This PR updates the multi-language schema-to-SDK generators (TypeScript, Python, Go, C#) to support JSON Schema $ref so shared definitions can be deduplicated and emitted once per language.

Changes:

• Adds shared $ref utilities (resolveRef, refTypeName, collectDefinitions) and expands ApiSchema to surface schema definitions.
• Refactors TypeScript RPC generation to compile a single combined schema (shared definitions + all RPC param/result types) in one pass.
• Updates Python/Go quicktype inputs and C# custom emitters to include/resolve referenced definitions.

Show a summary per file

File	Description
scripts/codegen/utils.ts	Adds $ref helpers and attempts $defs→definitions normalization in schema post-processing.
scripts/codegen/typescript.ts	Generates RPC types from one combined schema to dedupe $ref-shared types; re-adds experimental annotations post-compile.
scripts/codegen/python.ts	Includes shared definitions for quicktype to resolve $ref during session-event and RPC generation.
scripts/codegen/go.ts	Adds $ref handling to Go session-events custom generator; includes shared definitions for RPC quicktype generation.
scripts/codegen/csharp.ts	Adds $ref handling for session events + RPC generation, with on-demand referenced type emission.

Copilot's findings

Comments suppressed due to low confidence (1)

scripts/codegen/python.ts:23

• The import list includes isRpcMethod twice, which will cause a TypeScript compile error (“Duplicate identifier 'isRpcMethod'”). Remove the duplicate specifier.

import {
    getApiSchemaPath,
    getSessionEventsSchemaPath,
    isRpcMethod,
    postProcessSchema,
    writeGeneratedFile,
    collectDefinitions,
    isRpcMethod,
    isNodeFullyExperimental,
    type ApiSchema,
    type RpcMethod,
} from "./utils.js";

• Files reviewed: 5/5 changed files
• Comments generated: 7

[github-actions]

Generated by SDK Consistency Review Agent for issue #1062 · ● 2M

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds $ref support to all four language code generators and maintains strong cross-SDK consistency. Here's my analysis:

What was changed

All four generators were updated in a coordinated way:

Generator	Key changes
TypeScript	New normalizeSchemaForTypeScript + reuseSharedTitledSchemas; builds a single combined schema and compiles with unreachableDefinitions: true
Python	resolveRef/withSharedDefinitions integrated into both RPC and session-events generation
Go	$ref handling added to resolveGoPropertyType; definitions passed through GoCodegenCtx
C#	$ref handling added to resolveSessionPropertyType and resolveRpcType; on-demand class generation for referenced types

Consistency strengths

• ✅ Shared utilities: resolveRef, refTypeName, collectDefinitions, withSharedDefinitions, and resolveObjectSchema are all centralized in utils.ts and imported by all four generators — no per-language reimplementation of $ref resolution logic.
• ✅ CI codegen check passes: The "Verify generated files are up-to-date" job confirms all four SDKs' generated files correctly reflect what the updated generators produce.
• ✅ All SDK tests pass: TypeScript, Python, Go, and C# scenario and validation jobs all succeed.

Minor observation (not a blocker)

The TypeScript generator now uses unreachableDefinitions: true, which causes json-schema-to-typescript to export all schema definitions as top-level named TypeScript types — including types like SessionMode, UIElicitationResponseAction, and SessionLogLevel — even if they're only referenced indirectly. The Python, Go, and .NET generators don't have an equivalent option; they generate types only when reachable from an RPC method's params/result. Since those types are reachable in practice (they appear in method signatures in Python/Go/.NET), this doesn't cause missing functionality — it's just a slight asymmetry in how exhaustively each SDK surfaces schema-level types.

This asymmetry was a pre-existing characteristic of the TypeScript generator's approach and doesn't affect correctness. Not flagging it as a required change.

Summary

The PR is well-structured: $ref resolution logic is shared across generators, all four generators are updated, and CI confirms generated files are in sync. No cross-SDK consistency issues found.

Generated by SDK Consistency Review Agent for issue #1062 · ● 2.2M · ◷