refactor(client): group experimental SDK methods under client.experimental (#59072)

Author: kitlangton

AGENTS.md

@@ -169,6 +169,17 @@ const table = sqliteTable("session", {
 })
 ```
 
+### Experimental API
+
+- An experimental endpoint lives at `/api/experimental/<group>/...`, its OpenAPI identifier is `experimental.<group>.<method>`, and it lands in the SDK as `client.experimental.<group>.<method>`. Its description says "Experimental: may change without compatibility guarantees."
+- `packages/protocol/test/experimental-identifiers.test.ts` enforces the path and identifier match in both directions; the SDK namespace follows from the path.
+- An experimental field or parameter on a stable endpoint goes under an `experimental` key (`experimental.<name>`), the same way config does (`config.experimental.*`).
+- New endpoints and new default behaviors start experimental.
+- To graduate one, move the route out of `/api/experimental`, drop the `experimental.` prefix, and note it in `CHANGELOG.md`.
+- Experimental HTTP routes change without aliases: rename or remove the route, then update the callers.
+- A breaking move of shipped SDK or plugin API (including moving it under `experimental`) keeps the old path and type names as deprecated aliases of the new ones until the next minor, each marked `@deprecated` with the replacement and "Removed in the next minor". Generated SDK moves get them from the codegen (`compile(..., { aliases: true })` in `packages/client/script/generate.ts`), not by hand.
+- Experimental plugin hooks are named `experimental.*` (`experimental.ws.handshake`).
+
 ## Testing
 
 - Avoid mocks as much as possible, you shouldn't be using globalThis.\* at all unless it's the only option.

packages/app/src/home/projects/controller.tsx

@@ -123,7 +123,7 @@ export function createHomeProjectsController(home: HomeController) {
                 Schema.fromJsonString(Schema.Record(Schema.String, Schema.Json)),
               )(await file.text())
 
-              const api = home.server.context(conn).sdk.api.session
+              const api = home.server.context(conn).sdk.api.experimental.session
 
               // SAFETY: the import endpoint validates the transcript, including exports written by earlier releases.
               const imported = await api.import({

packages/app/src/providers/connect/mcp.ts

@@ -13,7 +13,7 @@ export type McpControls = {
   change: (name: string, enabled: boolean) => void
 }
 
-export function useMcpToggle(directory?: Accessor<string | undefined>, onSuccess?: () => unknown) {
+export function useMcpToggle(directory?: Accessor<string | undefined>, onSuccess?: () => void) {
   const data = useData()
   const serverSDK = useServerSDK()
   const platform = usePlatform()
@@ -27,19 +27,22 @@ export function useMcpToggle(directory?: Accessor<string | undefined>, onSuccess
 
   return useMutation(() => ({
     mutationFn: async (input: string | { name: string; enabled: boolean; directory?: string }) => {
-      const name = typeof input === "string" ? input : input.name
-      const ref = typeof input !== "string" && input.directory ? { directory: input.directory } : location()
+      // A bare name toggles the server; an object sets an explicit state.
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- discriminates this function's own input union
+      const request: { name: string; enabled?: boolean; directory?: string } = typeof input === "string" ? { name: input } : input
+      const name = request.name
+      const ref = request.directory ? { directory: request.directory } : location()
       const server = (await serverSDK.api.mcp.list({ location: ref })).data.find((item) => item.name === name)
 
-      if (!server || (server.status.status === "pending" && typeof input === "string")) return
-      const enabled = typeof input === "string" ? server.status.status !== "connected" : input.enabled
+      if (!server || (server.status.status === "pending" && request.enabled === undefined)) return
+      const enabled = request.enabled ?? server.status.status !== "connected"
 
       if (!enabled) {
-        await serverSDK.api.mcp.disconnect({ server: name, location: ref })
+        await serverSDK.api.experimental.mcp.disconnect({ server: name, location: ref })
       }
 
       if (enabled && server.status.status !== "needs_auth") {
-        await serverSDK.api.mcp.connect({ server: name, location: ref })
+        await serverSDK.api.experimental.mcp.connect({ server: name, location: ref })
       }
 
       data.location.mcp.server.invalidate(ref)

packages/app/src/runtime/server/sync.tsx

@@ -244,6 +244,7 @@ function createServerSyncContextInner(serverSDK: ServerSDK, data: Data) {
       if (update.time.archived) return rest
 
       const previous = projects.find((project) => project.id === update.id)
+
       // The wire payload carries no worktrees; keep the inventory this project already loaded.
       const next = withWorktreeInventory(
         previous ? updateProjectInfo(previous, update) : normalizeProjectInfo(update),
@@ -314,7 +315,7 @@ function createServerSyncContextInner(serverSDK: ServerSDK, data: Data) {
   const updateConfigMutation = useMutation(() => ({
     mutationFn: async (config: Config) => {
       // TODO: Restore config updates when the V2 client exposes a config API.
-      // await serverSDK.api.config.update({ config })
+      // await serverSDK.api.experimental.config.update({ config })
       throw new Error(`Config updates are unavailable: ${Object.keys(config).length} fields were not saved`)
     },
     onSuccess: () => {
@@ -343,10 +344,10 @@ function createServerSyncContextInner(serverSDK: ServerSDK, data: Data) {
         await toggleMcp({
           status,
           connect: async () => {
-            await serverSDK.api.mcp.connect({ server: name, location: { directory: key } })
+            await serverSDK.api.experimental.mcp.connect({ server: name, location: { directory: key } })
           },
           disconnect: async () => {
-            await serverSDK.api.mcp.disconnect({ server: name, location: { directory: key } })
+            await serverSDK.api.experimental.mcp.disconnect({ server: name, location: { directory: key } })
           },
           authenticate: async () => {
             const server = (await serverSDK.api.mcp.list({ location: { directory: key } })).data.find(

packages/app/src/session/revert.ts

@@ -88,7 +88,7 @@ export function createSessionRevert(input: {
     // Like the TUI, stop at the first failure instead of waiting on work that was never interrupted.
     if (!(await request(() => server.api.session.interrupt({ sessionID })))) return
 
-    if (!(await request(() => server.api.session.wait({ sessionID })))) return
+    if (!(await request(() => server.api.experimental.session.wait({ sessionID })))) return
 
     // Read before staging: the staged event can land before the request resolves.
     const prior = input.session.data.revertMessageID()

packages/app/src/settings/general/controllers.ts

@@ -59,7 +59,7 @@ export function createServerShellController(server: Accessor<ServerConnection.An
       const previous = state.latest
       actions.mutate({ ...previous, shell: value || undefined })
       void serverCtx()
-        .sdk.api.config.update({ shell: value || null })
+        .sdk.api.experimental.config.update({ shell: value || null })
         .catch((error) => {
           actions.mutate(previous)
           showToast({

packages/app/src/voice/tools.ts

@@ -120,6 +120,7 @@ export class VoiceTools {
 
       const seen = new Set<string>()
       const tabs = new Set(this.screen.tabs())
+
       // Best match first; among equal matches, top-level sessions with an open tab, then the most recent.
       const rank = (session: SessionInfo) =>
         (search.score(session) ?? 0) * 4 + (session.parentID ? 0 : 2) + (tabs.has(session.id) ? 1 : 0)
@@ -300,7 +301,7 @@ export class VoiceTools {
 
     if (call.name === "read_session" || call.name === "wait_for_session") {
       if (call.name === "wait_for_session") {
-        await api.session.wait({ sessionID }, { signal: AbortSignal.any([signal, AbortSignal.timeout(90_000)]) })
+        await api.experimental.session.wait({ sessionID }, { signal: AbortSignal.any([signal, AbortSignal.timeout(90_000)]) })
       }
 
       const [session, messages] = await Promise.all([

packages/app/src/voice/transport.ts

@@ -8,6 +8,13 @@ export class VoiceFailure extends Error {
   }
 }
 
+/** A client event sent over the Live data channel; the transport adds `event_id`. */
+export type VoiceClientEvent =
+  | { type: "session.input_audio.mute" | "session.input_audio.unmute" | "response.create" }
+  | { type: "session.update"; session: { delegation: { type: "responses"; responses: { instructions: string } } } }
+  | { type: "response.item.create"; item: { type: "function_call_output"; call_id: string; output: string } }
+  | { type: "session.commentary.append"; delegation_id: null; content: string }
+
 export class VoiceTransport {
   readonly abort = new AbortController()
   private peer = new RTCPeerConnection({ iceServers: [], bundlePolicy: "max-bundle", rtcpMuxPolicy: "require" })
@@ -78,7 +85,7 @@ export class VoiceTransport {
   async join(viewing: { id: string; title?: string }, tail: string) {
     const signal = AbortSignal.any([this.abort.signal, AbortSignal.timeout(35_000)])
     await this.context.resume()
-    const offered = await this.inputOptions.api.voice.models({ signal })
+    const offered = await this.inputOptions.api.experimental.voice.models({ signal })
 
     if (
       !offered.models.some(
@@ -106,7 +113,7 @@ export class VoiceTransport {
     })
     signal.throwIfAborted()
 
-    const response = await this.inputOptions.api.voice.session(
+    const response = await this.inputOptions.api.experimental.voice.session(
       {
         model: "gpt-live-1",
         session: {
@@ -153,7 +160,7 @@ export class VoiceTransport {
     this.timer = setInterval(() => this.inputOptions.levels(this.level(this.input), this.level(this.output)), 100)
   }
 
-  send(event: object) {
+  send(event: VoiceClientEvent) {
     if (this.ended || this.channel.readyState !== "open") throw new VoiceFailure("dropped")
     this.channel.send(JSON.stringify({ event_id: crypto.randomUUID(), ...event }))
   }

packages/app/src/workspaces/files/model.tsx

@@ -298,14 +298,14 @@ export const { use: useFile, provider: FileProvider } = createSimpleContext({
       const file = path.normalize(input)
 
       if (!file || path.absolute(file)) return
-      void serverSDK.api.file.watch({ path: file, location: { directory: scope() } }).catch(() => {})
+      void serverSDK.api.experimental.file.watch({ path: file, location: { directory: scope() } }).catch(() => {})
     }
 
     const unwatch = (input: string) => {
       const file = path.normalize(input)
 
       if (!file || path.absolute(file)) return
-      void serverSDK.api.file.unwatch({ path: file, location: { directory: scope() } }).catch(() => {})
+      void serverSDK.api.experimental.file.unwatch({ path: file, location: { directory: scope() } }).catch(() => {})
     }
 
     createEffect(() => {

packages/cli/src/acp/sessions.ts

@@ -101,7 +101,7 @@ export const make = Effect.fnUntraced(function* (input: {
             const config = mcpConfig(server)
             if (isDeepStrictEqual(registered.get(server.name), config)) return Effect.void
             registered.set(server.name, config)
-            return input.client.mcp.add({ server: server.name, location: { directory: attached.cwd }, config }).pipe(
+            return input.client.experimental.mcp.add({ server: server.name, location: { directory: attached.cwd }, config }).pipe(
               Effect.catch(ACPClient.classify),
               Effect.onError(() => Effect.sync(() => registered.delete(server.name))),
               Effect.uninterruptible,