Hide internal RPC methods from generated public API surface

The schema can now flag methods and types as internal. The codegen splits
internal RPC methods into parallel structures so they don't appear on the
public client API:

- TypeScript: createInternalServerRpc / createInternalSessionRpc factories
  alongside the existing public ones; client.ts wires connect() through a
  private internalRpc getter.
- C#: ConnectAsync and ConnectResult are emitted with the internal access
  modifier (real assembly-boundary access control).
- Python: parallel InternalServerRpc / InternalSessionRpc classes with
  ':meta private:' docstrings.
- Go: parallel InternalServerRpc / InternalSessionRpc types with their own
  unexported backing struct and NewInternalServerRpc constructor.
- Internal type definitions get a per-language doc-comment marker.
- New filterNodeByVisibility() helper in scripts/codegen/utils.ts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

dotnet/src/Generated/Rpc.cs

@@ -26,7 +26,7 @@ import {
     StreamMessageReader,
     StreamMessageWriter,
 } from "vscode-jsonrpc/node.js";
-import { createServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
+import { createServerRpc, createInternalServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
@@ -246,6 +246,7 @@ export class CopilotClient {
         Set<(event: SessionLifecycleEvent) => void>
     > = new Map();
     private _rpc: ReturnType<typeof createServerRpc> | null = null;
+    private _internalRpc: ReturnType<typeof createInternalServerRpc> | null = null;
     private processExitPromise: Promise<never> | null = null; // Rejects when CLI process exits
     private negotiatedProtocolVersion: number | null = null;
     /** Connection-level session filesystem config, set via constructor option. */
@@ -265,6 +266,20 @@ export class CopilotClient {
         return this._rpc;
     }
 
+    /**
+     * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
+     * @internal
+     */
+    private get internalRpc(): ReturnType<typeof createInternalServerRpc> {
+        if (!this.connection) {
+            throw new Error("Client is not connected. Call start() first.");
+        }
+        if (!this._internalRpc) {
+            this._internalRpc = createInternalServerRpc(this.connection);
+        }
+        return this._internalRpc;
+    }
+
     /**
      * Creates a new CopilotClient instance.
      *
@@ -1100,7 +1115,7 @@ export class CopilotClient {
 
         let serverVersion: number | undefined;
         try {
-            const result = await raceAgainstExit(this.rpc.connect({ token: this.effectiveConnectionToken }));
+            const result = await raceAgainstExit(this.internalRpc.connect({ token: this.effectiveConnectionToken }));
             serverVersion = result.protocolVersion;
         } catch (err) {
             if (err instanceof ResponseError && err.code === ErrorCodes.MethodNotFound) {

nodejs/src/client.ts

@@ -983,6 +983,16 @@ function emitRpcClass(
         resolveObjectSchema(schema, rpcDefinitions) ??
         resolveSchema(schema, rpcDefinitions) ??
         schema;
+    // Visibility is driven by the JSON Schema definition itself (set via
+    // `.asInternal()` on the originating Zod schema). The runtime schema
+    // generator enforces that no public method references an internal type,
+    // so it's safe to upgrade callers' default to internal here.
+    if (
+        (schema as Record<string, unknown>).visibility === "internal" ||
+        (effectiveSchema as Record<string, unknown>).visibility === "internal"
+    ) {
+        visibility = "internal";
+    }
     const schemaKey = stableStringify(effectiveSchema);
     const existingSchema = emittedRpcClassSchemas.get(className);
     if (existingSchema) {
@@ -1169,13 +1179,15 @@ function emitServerInstanceMethod(
     groupDeprecated: boolean
 ): void {
     const methodName = toPascalCase(name);
+    const isInternal = method.visibility === "internal";
+    const methodVisibility = isInternal ? "internal" : "public";
     const resultSchema = getMethodResultSchema(method);
     let resultClassName = !isVoidSchema(resultSchema) ? resultTypeName(method) : "";
     if (!isVoidSchema(resultSchema) && method.stability === "experimental") {
         experimentalRpcTypes.add(resultClassName);
     }
     if (isObjectSchema(resultSchema)) {
-        const resultClass = emitRpcClass(resultClassName, resultSchema!, "public", classes);
+        const resultClass = emitRpcClass(resultClassName, resultSchema!, methodVisibility, classes);
         if (resultClass) classes.push(resultClass);
     } else if (!isVoidSchema(resultSchema)) {
         resultClassName = emitNonObjectResultType(resultClassName, resultSchema!, classes);
@@ -1227,7 +1239,7 @@ function emitServerInstanceMethod(
     sigParams.push("CancellationToken cancellationToken = default");
 
     const taskType = !isVoidSchema(resultSchema) ? `Task<${resultClassName}>` : "Task";
-    lines.push(`${indent}public async ${taskType} ${methodName}Async(${sigParams.join(", ")})`);
+    lines.push(`${indent}${methodVisibility} async ${taskType} ${methodName}Async(${sigParams.join(", ")})`);
     lines.push(`${indent}{`);
     if (requestClassName && bodyAssignments.length > 0) {
         lines.push(`${indent}    var request = new ${requestClassName} { ${bodyAssignments.join(", ")} };`);
@@ -1275,13 +1287,15 @@ function emitSessionRpcClasses(node: Record<string, unknown>, classes: string[])
 
 function emitSessionMethod(key: string, method: RpcMethod, lines: string[], classes: string[], indent: string, groupExperimental: boolean, groupDeprecated: boolean): void {
     const methodName = toPascalCase(key);
+    const isInternal = method.visibility === "internal";
+    const methodVisibility = isInternal ? "internal" : "public";
     const resultSchema = getMethodResultSchema(method);
     let resultClassName = !isVoidSchema(resultSchema) ? resultTypeName(method) : "";
     if (!isVoidSchema(resultSchema) && method.stability === "experimental") {
         experimentalRpcTypes.add(resultClassName);
     }
     if (isObjectSchema(resultSchema)) {
-        const resultClass = emitRpcClass(resultClassName, resultSchema!, "public", classes);
+        const resultClass = emitRpcClass(resultClassName, resultSchema!, methodVisibility, classes);
         if (resultClass) classes.push(resultClass);
     } else if (!isVoidSchema(resultSchema)) {
         resultClassName = emitNonObjectResultType(resultClassName, resultSchema!, classes);
@@ -1327,7 +1341,7 @@ function emitSessionMethod(key: string, method: RpcMethod, lines: string[], clas
     sigParams.push("CancellationToken cancellationToken = default");
 
     const taskType = !isVoidSchema(resultSchema) ? `Task<${resultClassName}>` : "Task";
-    lines.push(`${indent}public async ${taskType} ${methodName}Async(${sigParams.join(", ")})`);
+    lines.push(`${indent}${methodVisibility} async ${taskType} ${methodName}Async(${sigParams.join(", ")})`);
     lines.push(`${indent}{`, `${indent}    var request = new ${requestClassName} { ${bodyAssignments.join(", ")} };`);
     if (!isVoidSchema(resultSchema)) {
         lines.push(`${indent}    return await CopilotClient.InvokeRpcAsync<${resultClassName}>(_rpc, "${method.rpcMethod}", [request], cancellationToken);`, `${indent}}`);

nodejs/src/generated/rpc.ts

@@ -13,6 +13,7 @@ import { FetchingJSONSchemaStore, InputData, JSONSchemaInput, quicktype } from "
 import { promisify } from "util";
 import {
     cloneSchemaForCodegen,
+    filterNodeByVisibility,
     fixNullableRequiredRefsInApiSchema,
     getApiSchemaPath,
     getRpcSchemaTypeName,
@@ -1161,6 +1162,21 @@ async function generateRpc(schemaPath?: string): Promise<void> {
             `// Deprecated: ${typeName} is deprecated and will be removed in a future version.\n$1`
         );
     }
+
+    // Annotate internal data types (driven by the JSON Schema definition's
+    // `visibility: "internal"` flag, set via `.asInternal()` on the Zod source).
+    const internalTypeNames = new Set<string>();
+    for (const [name, def] of Object.entries(allDefinitions)) {
+        if (def && typeof def === "object" && (def as Record<string, unknown>).visibility === "internal") {
+            internalTypeNames.add(name);
+        }
+    }
+    for (const typeName of internalTypeNames) {
+        qtCode = qtCode.replace(
+            new RegExp(`^(type ${typeName} struct)`, "m"),
+            `// Internal: ${typeName} is an internal SDK API and is not part of the public surface.\n$1`
+        );
+    }
     // Remove trailing blank lines from quicktype output before appending
     qtCode = qtCode.replace(/\n+$/, "");
     // Replace interface{} with any (quicktype emits the pre-1.18 form)
@@ -1196,12 +1212,18 @@ async function generateRpc(schemaPath?: string): Promise<void> {
 
     // Emit ServerRpc
     if (schema.server) {
-        emitRpcWrapper(lines, schema.server, false, resolveType, fieldNames);
+        const publicNode = filterNodeByVisibility(schema.server, "public");
+        if (publicNode) emitRpcWrapper(lines, publicNode, false, resolveType, fieldNames, "");
+        const internalNode = filterNodeByVisibility(schema.server, "internal");
+        if (internalNode) emitRpcWrapper(lines, internalNode, false, resolveType, fieldNames, "Internal");
     }
 
     // Emit SessionRpc
     if (schema.session) {
-        emitRpcWrapper(lines, schema.session, true, resolveType, fieldNames);
+        const publicNode = filterNodeByVisibility(schema.session, "public");
+        if (publicNode) emitRpcWrapper(lines, publicNode, true, resolveType, fieldNames, "");
+        const internalNode = filterNodeByVisibility(schema.session, "internal");
+        if (internalNode) emitRpcWrapper(lines, internalNode, true, resolveType, fieldNames, "Internal");
     }
 
     if (schema.clientSession) {
@@ -1257,13 +1279,17 @@ function emitApiGroup(
     }
 }
 
-function emitRpcWrapper(lines: string[], node: Record<string, unknown>, isSession: boolean, resolveType: (name: string) => string, fieldNames: Map<string, Map<string, string>>): void {
+function emitRpcWrapper(lines: string[], node: Record<string, unknown>, isSession: boolean, resolveType: (name: string) => string, fieldNames: Map<string, Map<string, string>>, classPrefix: string = ""): void {
     const groups = Object.entries(node).filter(([, v]) => typeof v === "object" && v !== null && !isRpcMethod(v));
     const topLevelMethods = Object.entries(node).filter(([, v]) => isRpcMethod(v));
 
-    const wrapperName = isSession ? "SessionRpc" : "ServerRpc";
+    const wrapperName = classPrefix + (isSession ? "SessionRpc" : "ServerRpc");
     const apiSuffix = "Api";
-    const serviceName = isSession ? "sessionApi" : "serverApi";
+    // Lowercase the prefix so the unexported service struct stays unexported in Go.
+    const prefixLower = classPrefix ? classPrefix.charAt(0).toLowerCase() + classPrefix.slice(1) : "";
+    const serviceName = prefixLower
+        ? prefixLower + (isSession ? "SessionApi" : "ServerApi")
+        : (isSession ? "sessionApi" : "serverApi");
 
     // Emit the common service struct (unexported, shared by all API groups via type cast)
     lines.push(`type ${serviceName} struct {`);
@@ -1274,7 +1300,7 @@ function emitRpcWrapper(lines: string[], node: Record<string, unknown>, isSessio
 
     // Emit API types for groups
     for (const [groupName, groupNode] of groups) {
-        const prefix = isSession ? "" : "Server";
+        const prefix = classPrefix + (isSession ? "" : "Server");
         const apiName = prefix + toPascalCase(groupName) + apiSuffix;
         const groupExperimental = isNodeFullyExperimental(groupNode as Record<string, unknown>);
         const groupDeprecated = isNodeFullyDeprecated(groupNode as Record<string, unknown>);
@@ -1288,12 +1314,14 @@ function emitRpcWrapper(lines: string[], node: Record<string, unknown>, isSessio
     const pad = (name: string) => name.padEnd(maxFieldLen);
 
     // Emit wrapper struct
-    lines.push(`// ${wrapperName} provides typed ${isSession ? "session" : "server"}-scoped RPC methods.`);
+    lines.push(classPrefix === "Internal"
+        ? `// ${wrapperName} provides internal SDK ${isSession ? "session" : "server"}-scoped RPC methods (handshake helpers etc.). Not part of the public API.`
+        : `// ${wrapperName} provides typed ${isSession ? "session" : "server"}-scoped RPC methods.`);
     lines.push(`type ${wrapperName} struct {`);
     lines.push(`\t${pad("common")} ${serviceName} // Reuse a single struct instead of allocating one for each service on the heap.`);
     lines.push(``);
     for (const [groupName] of groups) {
-        const prefix = isSession ? "" : "Server";
+        const prefix = classPrefix + (isSession ? "" : "Server");
         lines.push(`\t${pad(toPascalCase(groupName))} *${prefix}${toPascalCase(groupName)}${apiSuffix}`);
     }
     lines.push(`}`);
@@ -1315,7 +1343,7 @@ function emitRpcWrapper(lines: string[], node: Record<string, unknown>, isSessio
         lines.push(`\tr.common = ${serviceName}{client: client}`);
     }
     for (const [groupName] of groups) {
-        const prefix = isSession ? "" : "Server";
+        const prefix = classPrefix + (isSession ? "" : "Server");
         lines.push(`\tr.${toPascalCase(groupName)} = (*${prefix}${toPascalCase(groupName)}${apiSuffix})(&r.common)`);
     }
     lines.push(`\treturn r`);
@@ -1348,6 +1376,9 @@ function emitMethod(lines: string[], receiver: string, name: string, method: Rpc
     if (method.stability === "experimental" && !groupExperimental) {
         lines.push(`// Experimental: ${methodName} is an experimental API and may change or be removed in future versions.`);
     }
+    if (method.visibility === "internal") {
+        lines.push(`// Internal: ${methodName} is part of the SDK's internal handshake/plumbing; external callers should not use it.`);
+    }
     const sig = hasParams
         ? `func (a *${receiver}) ${methodName}(ctx context.Context, params *${paramsType}) (*${resultType}, error)`
         : `func (a *${receiver}) ${methodName}(ctx context.Context) (*${resultType}, error)`;