Skip to content

Naming improvements via codegen changes#1043

Merged
SteveSandersonMS merged 18 commits intomainfrom
stevesa/rpc-naming-improvments
Apr 14, 2026
Merged

Naming improvements via codegen changes#1043
SteveSandersonMS merged 18 commits intomainfrom
stevesa/rpc-naming-improvments

Conversation

@SteveSandersonMS
Copy link
Copy Markdown
Contributor

@SteveSandersonMS SteveSandersonMS commented Apr 8, 2026

Changes to RPC naming convention changes to fix #1035

This PR improves generated public type names across the SDKs by moving naming decisions into the shared schema/codegen pipeline instead of relying on language-specific quirks.

The goal is to make generated names:

  • shorter when the old names were just path concatenation noise
  • more specific when the old names were too generic to be useful
  • more consistent across TypeScript, C#, Go, and Python
  • more stable, because naming now follows a common set of rules plus explicit schema-local overrides where the API really wants a specific public name

Main naming rules

The naming is now mostly mechanical rather than hand-curated:

  1. Derive names from the RPC method / event identity first

    • Example: account.getQuota becomes an AccountQuota root instead of AccountGetQuotaResult.
  2. Drop generic namespace and filler words

    • Strip prefixes like session.
    • Strip terminal filler verbs like get, read, and list when they are only structural
  3. Singularize list entities

    • Example: models.list uses Model for nested item types and ModelList for the top-level result
  4. Keep top-level wrapper words only when they are actually useful

    • Request / Result remain for top-level params/results
    • nested helper types stop inheriting repeated ...Request...Result...Value...Item noise
  5. Drop purely structural wrapper property names in nested helpers

    • Words like data, result, request, response, kind, value, etc. are removed when they are just containers, not meaningful domain terms
  6. Normalize overlapping words

    • Avoid awkward duplication like requested + request
  7. Use explicit schema-local names for true API surface decisions

    • When the API really wants a specific public name, that name is declared in the schema instead of in generator-side override maps

Before / after examples

Previously too long

Before After
AccountGetQuotaResultQuotaSnapshotsValue AccountQuotaSnapshot
SessionPermissionsHandlePendingPermissionRequestResult PermissionRequestResult
SessionToolsHandlePendingToolCallResult HandleToolCallResult
SessionUiElicitationRequestRequestedSchema UiElicitationSchema
SessionUiHandlePendingElicitationRequestResult UiElicitationResponse
SessionUiHandlePendingElicitationResult UiElicitationResult
ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme ToolExecutionCompleteContentResourceLinkIconTheme
UserMessageDataAttachmentsItemSelectionSelectionEnd UserMessageAttachmentSelectionDetailsEnd

Previously too short / too generic

Before After
Entry SessionFsReaddirWithTypesEntry / SessionFSReaddirWithTypesEntry
End UserMessageAttachmentSelectionDetailsEnd
Mode SessionMode
SessionModeGetResultMode SessionMode

A few especially notable cases

  • The worst "path explosion" example was the old icon theme helper name:

    • ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme
    • now: ToolExecutionCompleteContentResourceLinkIconTheme
  • The worst "too generic to understand in isolation" examples were names like:

    • Entry
    • End
    • Mode

    Those now carry enough domain context to be understandable in generated SDKs without needing to inspect the surrounding method/property path.

API-specific naming that is now explicit

A few names are intentionally chosen as API surface names rather than just synthesized mechanically, for example:

  • UiElicitationResponse
  • UiElicitationResult
  • HandlePendingElicitationRequest
  • PermissionDecision
  • PermissionDecisionRequest
  • PermissionRequestResult
  • ModeGetResult
  • ModeSetResult
  • HandleToolCallResult

That keeps the generator logic generic while still letting the schema declare clear public names where needed.

TypeScript note

TypeScript still avoids exploding the surface area with every synthesized helper as a named export. Explicit public names are preserved where intended, while synthetic helper naming is mainly used to improve the non-TS SDKs and shared generation consistency.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review all codegenerated type names; provide better names in many cases

5 participants