Skip to content

Commit 2bfbb47

Browse files
stephentoubCopilot
stephentoub
and
Copilot
authored
Add experimental API annotations from schema stability markers (#875)
* Add experimental API annotations from schema stability markers Read the 'stability' field from api.schema.json and propagate it to generated code in all four SDK languages. APIs marked as experimental in the schema (fleet, agent, compaction) now carry appropriate annotations in the generated output. Changes to codegen scripts (scripts/codegen/): - utils.ts: Add stability field to RpcMethod; add isNodeFullyExperimental helper - csharp.ts: Emit [Experimental(Diagnostics.Experimental)] on types and API classes - typescript.ts: Emit /** @experimental */ JSDoc on types and groups - python.ts: Emit # Experimental comments on types and API classes, docstrings on methods - go.ts: Emit // Experimental: comments on types and API structs Design decisions: - When all methods in a group are experimental, the group/class is annotated and individual methods are not (annotation is inherited) - Data types (request/result) for experimental methods are also annotated - C# uses a Diagnostics.Experimental const ("GHCP001") referenced by all attributes - SDK csproj suppresses GHCP001 internally; consumers still see warnings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Strip trailing whitespace from Go quicktype output Address review feedback: quicktype generates comments with trailing whitespace which fails gofmt checks. Add a post-processing step to strip trailing whitespace from the quicktype output before writing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: use tabs for Go indentation and column-align struct fields gofmt requires tab indentation (not spaces) and column-aligns struct field declarations and composite literal keys. Updated the Go codegen to emit tabs for all indentation and compute proper padding for field alignment in wrapper structs and constructors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: use multi-line if-return blocks for gofmt compatibility gofmt expands single-line 'if err != nil { return nil, err }' into multi-line blocks. Updated Go codegen to emit the multi-line form directly, avoiding the gofmt diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: expand single-line struct defs to multi-line for gofmt gofmt expands single-line struct definitions with semicolons into multi-line format. Updated the Go codegen to emit API struct definitions in multi-line format directly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: collapse quicktype column alignment for gofmt compatibility quicktype emits wide-spaced struct fields for column alignment, but gofmt doesn't column-align when fields have interleaved comments. Added post-processing to collapse excessive spacing in quicktype struct field lines and remove trailing blank lines from quicktype output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: regenerate Go output with gofmt for proper formatting Removed manual quicktype column-alignment workaround and regenerated with Go installed locally so formatGoFile() runs gofmt properly. This ensures the committed output exactly matches what CI produces. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 698b259 commit 2bfbb47

File tree

11 files changed

+262
-46
lines changed

11 files changed

+262
-46
lines changed

‎dotnet/src/Generated/Rpc.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,20 @@
55
// AUTO-GENERATED FILE - DO NOT EDIT
66
// Generated from: api.schema.json
77

8+
using System.Diagnostics.CodeAnalysis;
89
using System.Text.Json;
910
using System.Text.Json.Serialization;
1011
using StreamJsonRpc;
1112

1213
namespace GitHub.Copilot.SDK.Rpc;
1314

15+
/// <summary>Diagnostic IDs for the Copilot SDK.</summary>
16+
internal static class Diagnostics
17+
{
18+
/// <summary>Indicates an experimental API that may change or be removed.</summary>
19+
internal const string Experimental = "GHCP001";
20+
}
21+
1422
/// <summary>RPC data type for Ping operations.</summary>
1523
public class PingResult
1624
{
@@ -427,6 +435,7 @@ internal class SessionWorkspaceCreateFileRequest
427435
}
428436

429437
/// <summary>RPC data type for SessionFleetStart operations.</summary>
438+
[Experimental(Diagnostics.Experimental)]
430439
public class SessionFleetStartResult
431440
{
432441
/// <summary>Whether fleet mode was successfully activated.</summary>
@@ -435,6 +444,7 @@ public class SessionFleetStartResult
435444
}
436445

437446
/// <summary>RPC data type for SessionFleetStart operations.</summary>
447+
[Experimental(Diagnostics.Experimental)]
438448
internal class SessionFleetStartRequest
439449
{
440450
/// <summary>Target session identifier.</summary>
@@ -463,6 +473,7 @@ public class Agent
463473
}
464474

465475
/// <summary>RPC data type for SessionAgentList operations.</summary>
476+
[Experimental(Diagnostics.Experimental)]
466477
public class SessionAgentListResult
467478
{
468479
/// <summary>Available custom agents.</summary>
@@ -471,6 +482,7 @@ public class SessionAgentListResult
471482
}
472483

473484
/// <summary>RPC data type for SessionAgentList operations.</summary>
485+
[Experimental(Diagnostics.Experimental)]
474486
internal class SessionAgentListRequest
475487
{
476488
/// <summary>Target session identifier.</summary>
@@ -495,6 +507,7 @@ public class SessionAgentGetCurrentResultAgent
495507
}
496508

497509
/// <summary>RPC data type for SessionAgentGetCurrent operations.</summary>
510+
[Experimental(Diagnostics.Experimental)]
498511
public class SessionAgentGetCurrentResult
499512
{
500513
/// <summary>Currently selected custom agent, or null if using the default agent.</summary>
@@ -503,6 +516,7 @@ public class SessionAgentGetCurrentResult
503516
}
504517

505518
/// <summary>RPC data type for SessionAgentGetCurrent operations.</summary>
519+
[Experimental(Diagnostics.Experimental)]
506520
internal class SessionAgentGetCurrentRequest
507521
{
508522
/// <summary>Target session identifier.</summary>
@@ -527,6 +541,7 @@ public class SessionAgentSelectResultAgent
527541
}
528542

529543
/// <summary>RPC data type for SessionAgentSelect operations.</summary>
544+
[Experimental(Diagnostics.Experimental)]
530545
public class SessionAgentSelectResult
531546
{
532547
/// <summary>The newly selected custom agent.</summary>
@@ -535,6 +550,7 @@ public class SessionAgentSelectResult
535550
}
536551

537552
/// <summary>RPC data type for SessionAgentSelect operations.</summary>
553+
[Experimental(Diagnostics.Experimental)]
538554
internal class SessionAgentSelectRequest
539555
{
540556
/// <summary>Target session identifier.</summary>
@@ -547,11 +563,13 @@ internal class SessionAgentSelectRequest
547563
}
548564

549565
/// <summary>RPC data type for SessionAgentDeselect operations.</summary>
566+
[Experimental(Diagnostics.Experimental)]
550567
public class SessionAgentDeselectResult
551568
{
552569
}
553570

554571
/// <summary>RPC data type for SessionAgentDeselect operations.</summary>
572+
[Experimental(Diagnostics.Experimental)]
555573
internal class SessionAgentDeselectRequest
556574
{
557575
/// <summary>Target session identifier.</summary>
@@ -560,6 +578,7 @@ internal class SessionAgentDeselectRequest
560578
}
561579

562580
/// <summary>RPC data type for SessionCompactionCompact operations.</summary>
581+
[Experimental(Diagnostics.Experimental)]
563582
public class SessionCompactionCompactResult
564583
{
565584
/// <summary>Whether compaction completed successfully.</summary>
@@ -576,6 +595,7 @@ public class SessionCompactionCompactResult
576595
}
577596

578597
/// <summary>RPC data type for SessionCompactionCompact operations.</summary>
598+
[Experimental(Diagnostics.Experimental)]
579599
internal class SessionCompactionCompactRequest
580600
{
581601
/// <summary>Target session identifier.</summary>
@@ -1000,6 +1020,7 @@ public async Task<SessionWorkspaceCreateFileResult> CreateFileAsync(string path,
10001020
}
10011021

10021022
/// <summary>Provides session-scoped Fleet APIs.</summary>
1023+
[Experimental(Diagnostics.Experimental)]
10031024
public class FleetApi
10041025
{
10051026
private readonly JsonRpc _rpc;
@@ -1020,6 +1041,7 @@ public async Task<SessionFleetStartResult> StartAsync(string? prompt = null, Can
10201041
}
10211042

10221043
/// <summary>Provides session-scoped Agent APIs.</summary>
1044+
[Experimental(Diagnostics.Experimental)]
10231045
public class AgentApi
10241046
{
10251047
private readonly JsonRpc _rpc;
@@ -1061,6 +1083,7 @@ public async Task<SessionAgentDeselectResult> DeselectAsync(CancellationToken ca
10611083
}
10621084

10631085
/// <summary>Provides session-scoped Compaction APIs.</summary>
1086+
[Experimental(Diagnostics.Experimental)]
10641087
public class CompactionApi
10651088
{
10661089
private readonly JsonRpc _rpc;

‎dotnet/src/GitHub.Copilot.SDK.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@
2020
<EmbedUntrackedSources>true</EmbedUntrackedSources>
2121
</PropertyGroup>
2222

23+
<PropertyGroup>
24+
<NoWarn>$(NoWarn);GHCP001</NoWarn>
25+
</PropertyGroup>
26+
2327
<PropertyGroup Condition="'$(CI)' == 'true' or '$(TF_BUILD)' == 'true'">
2428
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
2529
</PropertyGroup>

‎dotnet/test/GitHub.Copilot.SDK.Test.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
<PropertyGroup>
44
<IsPackable>false</IsPackable>
5+
<NoWarn>$(NoWarn);GHCP001</NoWarn>
56
</PropertyGroup>
67

78
<PropertyGroup>

‎go/rpc/generated_rpc.go‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,16 +208,19 @@ type SessionWorkspaceCreateFileParams struct {
208208
Path string `json:"path"`
209209
}
210210

211+
// Experimental: SessionFleetStartResult is part of an experimental API and may change or be removed.
211212
type SessionFleetStartResult struct {
212213
// Whether fleet mode was successfully activated
213214
Started bool `json:"started"`
214215
}
215216

217+
// Experimental: SessionFleetStartParams is part of an experimental API and may change or be removed.
216218
type SessionFleetStartParams struct {
217219
// Optional user prompt to combine with fleet instructions
218220
Prompt *string `json:"prompt,omitempty"`
219221
}
220222

223+
// Experimental: SessionAgentListResult is part of an experimental API and may change or be removed.
221224
type SessionAgentListResult struct {
222225
// Available custom agents
223226
Agents []AgentElement `json:"agents"`
@@ -232,6 +235,7 @@ type AgentElement struct {
232235
Name string `json:"name"`
233236
}
234237

238+
// Experimental: SessionAgentGetCurrentResult is part of an experimental API and may change or be removed.
235239
type SessionAgentGetCurrentResult struct {
236240
// Currently selected custom agent, or null if using the default agent
237241
Agent *SessionAgentGetCurrentResultAgent `json:"agent"`
@@ -246,6 +250,7 @@ type SessionAgentGetCurrentResultAgent struct {
246250
Name string `json:"name"`
247251
}
248252

253+
// Experimental: SessionAgentSelectResult is part of an experimental API and may change or be removed.
249254
type SessionAgentSelectResult struct {
250255
// The newly selected custom agent
251256
Agent SessionAgentSelectResultAgent `json:"agent"`
@@ -261,14 +266,17 @@ type SessionAgentSelectResultAgent struct {
261266
Name string `json:"name"`
262267
}
263268

269+
// Experimental: SessionAgentSelectParams is part of an experimental API and may change or be removed.
264270
type SessionAgentSelectParams struct {
265271
// Name of the custom agent to select
266272
Name string `json:"name"`
267273
}
268274

275+
// Experimental: SessionAgentDeselectResult is part of an experimental API and may change or be removed.
269276
type SessionAgentDeselectResult struct {
270277
}
271278

279+
// Experimental: SessionCompactionCompactResult is part of an experimental API and may change or be removed.
272280
type SessionCompactionCompactResult struct {
273281
// Number of messages removed during compaction
274282
MessagesRemoved float64 `json:"messagesRemoved"`
@@ -402,7 +410,9 @@ type ResultUnion struct {
402410
String *string
403411
}
404412

405-
type ServerModelsRpcApi struct{ client *jsonrpc2.Client }
413+
type ServerModelsRpcApi struct {
414+
client *jsonrpc2.Client
415+
}
406416

407417
func (a *ServerModelsRpcApi) List(ctx context.Context) (*ModelsListResult, error) {
408418
raw, err := a.client.Request("models.list", map[string]interface{}{})
@@ -416,7 +426,9 @@ func (a *ServerModelsRpcApi) List(ctx context.Context) (*ModelsListResult, error
416426
return &result, nil
417427
}
418428

419-
type ServerToolsRpcApi struct{ client *jsonrpc2.Client }
429+
type ServerToolsRpcApi struct {
430+
client *jsonrpc2.Client
431+
}
420432

421433
func (a *ServerToolsRpcApi) List(ctx context.Context, params *ToolsListParams) (*ToolsListResult, error) {
422434
raw, err := a.client.Request("tools.list", params)
@@ -430,7 +442,9 @@ func (a *ServerToolsRpcApi) List(ctx context.Context, params *ToolsListParams) (
430442
return &result, nil
431443
}
432444

433-
type ServerAccountRpcApi struct{ client *jsonrpc2.Client }
445+
type ServerAccountRpcApi struct {
446+
client *jsonrpc2.Client
447+
}
434448

435449
func (a *ServerAccountRpcApi) GetQuota(ctx context.Context) (*AccountGetQuotaResult, error) {
436450
raw, err := a.client.Request("account.getQuota", map[string]interface{}{})
@@ -641,6 +655,7 @@ func (a *WorkspaceRpcApi) CreateFile(ctx context.Context, params *SessionWorkspa
641655
return &result, nil
642656
}
643657

658+
// Experimental: FleetRpcApi contains experimental APIs that may change or be removed.
644659
type FleetRpcApi struct {
645660
client *jsonrpc2.Client
646661
sessionID string
@@ -664,6 +679,7 @@ func (a *FleetRpcApi) Start(ctx context.Context, params *SessionFleetStartParams
664679
return &result, nil
665680
}
666681

682+
// Experimental: AgentRpcApi contains experimental APIs that may change or be removed.
667683
type AgentRpcApi struct {
668684
client *jsonrpc2.Client
669685
sessionID string
@@ -724,6 +740,7 @@ func (a *AgentRpcApi) Deselect(ctx context.Context) (*SessionAgentDeselectResult
724740
return &result, nil
725741
}
726742

743+
// Experimental: CompactionRpcApi contains experimental APIs that may change or be removed.
727744
type CompactionRpcApi struct {
728745
client *jsonrpc2.Client
729746
sessionID string

‎nodejs/src/generated/rpc.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,13 +340,15 @@ export interface SessionWorkspaceCreateFileParams {
340340
content: string;
341341
}
342342

343+
/** @experimental */
343344
export interface SessionFleetStartResult {
344345
/**
345346
* Whether fleet mode was successfully activated
346347
*/
347348
started: boolean;
348349
}
349350

351+
/** @experimental */
350352
export interface SessionFleetStartParams {
351353
/**
352354
* Target session identifier
@@ -358,6 +360,7 @@ export interface SessionFleetStartParams {
358360
prompt?: string;
359361
}
360362

363+
/** @experimental */
361364
export interface SessionAgentListResult {
362365
/**
363366
* Available custom agents
@@ -378,13 +381,15 @@ export interface SessionAgentListResult {
378381
}[];
379382
}
380383

384+
/** @experimental */
381385
export interface SessionAgentListParams {
382386
/**
383387
* Target session identifier
384388
*/
385389
sessionId: string;
386390
}
387391

392+
/** @experimental */
388393
export interface SessionAgentGetCurrentResult {
389394
/**
390395
* Currently selected custom agent, or null if using the default agent
@@ -405,13 +410,15 @@ export interface SessionAgentGetCurrentResult {
405410
} | null;
406411
}
407412

413+
/** @experimental */
408414
export interface SessionAgentGetCurrentParams {
409415
/**
410416
* Target session identifier
411417
*/
412418
sessionId: string;
413419
}
414420

421+
/** @experimental */
415422
export interface SessionAgentSelectResult {
416423
/**
417424
* The newly selected custom agent
@@ -432,6 +439,7 @@ export interface SessionAgentSelectResult {
432439
};
433440
}
434441

442+
/** @experimental */
435443
export interface SessionAgentSelectParams {
436444
/**
437445
* Target session identifier
@@ -443,15 +451,18 @@ export interface SessionAgentSelectParams {
443451
name: string;
444452
}
445453

454+
/** @experimental */
446455
export interface SessionAgentDeselectResult {}
447456

457+
/** @experimental */
448458
export interface SessionAgentDeselectParams {
449459
/**
450460
* Target session identifier
451461
*/
452462
sessionId: string;
453463
}
454464

465+
/** @experimental */
455466
export interface SessionCompactionCompactResult {
456467
/**
457468
* Whether compaction completed successfully
@@ -467,6 +478,7 @@ export interface SessionCompactionCompactResult {
467478
messagesRemoved: number;
468479
}
469480

481+
/** @experimental */
470482
export interface SessionCompactionCompactParams {
471483
/**
472484
* Target session identifier
@@ -660,10 +672,12 @@ export function createSessionRpc(connection: MessageConnection, sessionId: strin
660672
createFile: async (params: Omit<SessionWorkspaceCreateFileParams, "sessionId">): Promise<SessionWorkspaceCreateFileResult> =>
661673
connection.sendRequest("session.workspace.createFile", { sessionId, ...params }),
662674
},
675+
/** @experimental */
663676
fleet: {
664677
start: async (params: Omit<SessionFleetStartParams, "sessionId">): Promise<SessionFleetStartResult> =>
665678
connection.sendRequest("session.fleet.start", { sessionId, ...params }),
666679
},
680+
/** @experimental */
667681
agent: {
668682
list: async (): Promise<SessionAgentListResult> =>
669683
connection.sendRequest("session.agent.list", { sessionId }),
@@ -674,6 +688,7 @@ export function createSessionRpc(connection: MessageConnection, sessionId: strin
674688
deselect: async (): Promise<SessionAgentDeselectResult> =>
675689
connection.sendRequest("session.agent.deselect", { sessionId }),
676690
},
691+
/** @experimental */
677692
compaction: {
678693
compact: async (): Promise<SessionCompactionCompactResult> =>
679694
connection.sendRequest("session.compaction.compact", { sessionId }),

0 commit comments

Comments
 (0)