feat: Stabilize elicitation APIs

scripts/generate.js

@@ -10,8 +10,8 @@ import * as fs from "fs/promises";
 import { dirname } from "path";
 import * as prettier from "prettier";
 
-const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.20.0";
-const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.2";
+const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.21.0";
+const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.3";
 const CHECK_GENERATED = process.argv.includes("--check");
 
 // ── Extensible-union pipeline ────────────────────────────────────────────────

src/acp.test.ts

@@ -2685,8 +2685,8 @@ describe("Connection", () => {
 
         async function exerciseElicitation(agentClient: AgentSideConnection) {
           const response =
-            await agentClient.unstable_createElicitation(elicitationRequest);
-          await agentClient.unstable_completeElicitation({
+            await agentClient.createElicitation(elicitationRequest);
+          await agentClient.completeElicitation({
             elicitationId: "elicitation-1",
           });
           return response;
@@ -2699,14 +2699,14 @@ describe("Connection", () => {
                 return { outcome: { outcome: "cancelled" } };
               },
               sessionUpdate(): void {},
-              unstable_createElicitation(params) {
+              createElicitation(params) {
                 received.push(["create", params.message]);
                 return {
                   action: "accept",
                   content: { name: "Alice" },
                 };
               },
-              unstable_completeElicitation(params) {
+              completeElicitation(params) {
                 received.push(["complete", params.elicitationId]);
               },
             }),
@@ -5910,7 +5910,7 @@ describe("Connection", () => {
       }
       async sessionUpdate(_: SessionNotification): Promise<void> {}
 
-      async unstable_createElicitation(
+      async createElicitation(
         params: CreateElicitationRequest,
       ): Promise<CreateElicitationResponse> {
         receivedRequest = params;
@@ -5919,7 +5919,7 @@ describe("Connection", () => {
           content: { name: "Alice" },
         };
       }
-      async unstable_completeElicitation(
+      async completeElicitation(
         params: CompleteElicitationNotification,
       ): Promise<void> {
         receivedNotification = params;
@@ -5954,7 +5954,7 @@ describe("Connection", () => {
     );
 
     // Test form-mode elicitation request
-    const response = await clientConnection.unstable_createElicitation({
+    const response = await clientConnection.createElicitation({
       sessionId: "test-session",
       mode: "form",
       message: "Please enter your name",
@@ -5973,7 +5973,7 @@ describe("Connection", () => {
 
     // Test url-mode elicitation request
     receivedRequest = undefined;
-    const urlResponse = await clientConnection.unstable_createElicitation({
+    const urlResponse = await clientConnection.createElicitation({
       sessionId: "test-session",
       mode: "url",
       message: "Please authenticate",
@@ -5988,7 +5988,7 @@ describe("Connection", () => {
     expect((receivedRequest as any)?.elicitationId).toBe("elic-url-1");
 
     // Test elicitation complete notification
-    await clientConnection.unstable_completeElicitation({
+    await clientConnection.completeElicitation({
       elicitationId: "elic-1",
     });
 
@@ -6044,13 +6044,13 @@ describe("Connection", () => {
       ndJsonStream(agentToClient.writable, clientToAgent.readable),
     );
 
-    await clientConnection.unstable_completeElicitation({
+    await clientConnection.completeElicitation({
       elicitationId: "elic-1",
     });
   });
 
   it("rejects elicitation request when client does not implement handler", async () => {
-    // Client WITHOUT unstable_createElicitation
+    // Client WITHOUT createElicitation
     class TestClient implements Client {
       async writeTextFile(
         _: WriteTextFileRequest,
@@ -6098,7 +6098,7 @@ describe("Connection", () => {
     );
 
     await expect(
-      clientConnection.unstable_createElicitation({
+      clientConnection.createElicitation({
         sessionId: "test-session",
         mode: "form",
         message: "Enter your name",

src/acp.ts

@@ -1378,7 +1378,7 @@ const clientRequestSpecs = {
     validate.zKillTerminalRequest,
     emptyObjectResponse,
   ),
-  unstable_createElicitation: requestSpec<
+  createElicitation: requestSpec<
     schema.CreateElicitationRequest,
     schema.CreateElicitationResponse
   >(
@@ -1392,11 +1392,10 @@ const clientNotificationSpecs = {
     schema.CLIENT_METHODS.session_update,
     validate.zSessionNotification,
   ),
-  unstable_completeElicitation:
-    notificationSpec<schema.CompleteElicitationNotification>(
-      schema.CLIENT_METHODS.elicitation_complete,
-      validate.zCompleteElicitationNotification,
-    ),
+  completeElicitation: notificationSpec<schema.CompleteElicitationNotification>(
+    schema.CLIENT_METHODS.elicitation_complete,
+    validate.zCompleteElicitationNotification,
+  ),
 };
 
 const agentRequestSpecsByMethod = specsByMethod(agentRequestSpecs);
@@ -2605,14 +2604,14 @@ function legacyClientApp(implementation: Client): ClientApp {
       async (ctx) => (await implementation.killTerminal?.(ctx.params)) ?? {},
     );
 
-  if (implementation.unstable_createElicitation) {
+  if (implementation.createElicitation) {
     app.onRequest(schema.CLIENT_METHODS.elicitation_create, (ctx) =>
-      implementation.unstable_createElicitation!(ctx.params),
+      implementation.createElicitation!(ctx.params),
     );
   }
-  if (implementation.unstable_completeElicitation) {
+  if (implementation.completeElicitation) {
     app.onNotification(schema.CLIENT_METHODS.elicitation_complete, (ctx) =>
-      implementation.unstable_completeElicitation!(ctx.params),
+      implementation.completeElicitation!(ctx.params),
     );
   }
 
@@ -2799,16 +2798,8 @@ export class AgentSideConnection {
     );
   }
 
-  /**
-   * **UNSTABLE**
-   *
-   * This capability is not part of the spec yet, and may be removed or changed at any point.
-   *
-   * Creates an elicitation to request input from the user.
-   *
-   * @experimental
-   */
-  unstable_createElicitation(
+  /** Creates an elicitation to request input from the user. */
+  createElicitation(
     params: schema.CreateElicitationRequest,
   ): Promise<schema.CreateElicitationResponse> {
     return this.connection.sendRequest(
@@ -2817,16 +2808,8 @@ export class AgentSideConnection {
     );
   }
 
-  /**
-   * **UNSTABLE**
-   *
-   * This capability is not part of the spec yet, and may be removed or changed at any point.
-   *
-   * Notifies the client that a URL-based elicitation is complete.
-   *
-   * @experimental
-   */
-  unstable_completeElicitation(
+  /** Notifies the client that a URL-based elicitation is complete. */
+  completeElicitation(
     params: schema.CompleteElicitationNotification,
   ): Promise<void> {
     return this.connection.sendNotification(
@@ -3860,29 +3843,13 @@ export interface Client {
     params: schema.KillTerminalRequest,
   ): MaybePromise<schema.KillTerminalResponse | void>;
 
-  /**
-   * **UNSTABLE**
-   *
-   * This capability is not part of the spec yet, and may be removed or changed at any point.
-   *
-   * Creates an elicitation to request input from the user.
-   *
-   * @experimental
-   */
-  unstable_createElicitation?(
+  /** Creates an elicitation to request input from the user. */
+  createElicitation?(
     params: schema.CreateElicitationRequest,
   ): MaybePromise<schema.CreateElicitationResponse>;
 
-  /**
-   * **UNSTABLE**
-   *
-   * This capability is not part of the spec yet, and may be removed or changed at any point.
-   *
-   * Called when a URL-based elicitation is complete.
-   *
-   * @experimental
-   */
-  unstable_completeElicitation?(
+  /** Called when a URL-based elicitation is complete. */
+  completeElicitation?(
     params: schema.CompleteElicitationNotification,
   ): MaybePromise<void>;
 

src/schema/guards.gen.ts

@@ -48,17 +48,11 @@ const zGuardCreateElicitationResponseCancel = z.object({
 });
 
 /**
- * **UNSTABLE**
- *
- * This capability is not part of the spec yet, and may be removed or changed at any point.
- *
  * Request from the agent to elicit structured user input.
  *
  * The agent sends this to the client to request information from the user,
  * either via a form or by directing them to a URL.
  * Elicitations are tied to a session (optionally a tool call) or a request.
- *
- * @experimental
  */
 export type CreateElicitationRequest = types.CreateElicitationRequest;
 /**
@@ -75,8 +69,6 @@ export type CreateElicitationRequest = types.CreateElicitationRequest;
  * another variant's payload) guards are conservative where wire parsing
  * may still accept the value — narrow wire-parsed values when exact
  * parity matters.
- *
- * @experimental
  */
 export const CreateElicitationRequest = {
   /** Narrow to the `form` variant, validating its payload. */
@@ -271,13 +263,7 @@ export const MultiSelectItems = {
 } as const;
 
 /**
- * **UNSTABLE**
- *
- * This capability is not part of the spec yet, and may be removed or changed at any point.
- *
  * Response from the client to an elicitation request.
- *
- * @experimental
  */
 export type CreateElicitationResponse = types.CreateElicitationResponse;
 /**
@@ -294,8 +280,6 @@ export type CreateElicitationResponse = types.CreateElicitationResponse;
  * another variant's payload) guards are conservative where wire parsing
  * may still accept the value — narrow wire-parsed values when exact
  * parity matters.
- *
- * @experimental
  */
 export const CreateElicitationResponse = {
   /** Narrow to the `accept` variant, validating its payload. */

src/schema/index.ts

@@ -12,10 +12,8 @@ export type {
   AuthCapabilities,
   AuthenticateRequest,
   AuthenticateResponse,
-  AuthEnvVar,
   AuthMethod,
   AuthMethodAgent,
-  AuthMethodEnvVar,
   AuthMethodId,
   AuthMethodTerminal,
   AvailableCommand,
@@ -36,6 +34,11 @@ export type {
   CloseNesResponse,
   CloseSessionRequest,
   CloseSessionResponse,
+  CompactionCapabilities,
+  CompactionId,
+  CompactionStatus,
+  CompactionSummaryChunk,
+  CompactionUpdate,
   CompleteElicitationNotification,
   ConfigOptionUpdate,
   ConnectMcpRequest,