protocol cleanup (#9147)

2026-05-22 17:04:46 -04:00
parent 48d20e72d3
commit 0a958213db
19 changed files with 2378 additions and 1788 deletions
@@ -23,7 +23,7 @@ pub struct CustomMethodSchema {

 /// Add an extension to an active session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/extensions/add", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/extensions/add", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct AddExtensionRequest {
    pub session_id: String,
@@ -34,7 +34,7 @@ pub struct AddExtensionRequest {

 /// Remove an extension from an active session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/extensions/remove", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/extensions/remove", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct RemoveExtensionRequest {
    pub session_id: String,
@@ -43,7 +43,7 @@ pub struct RemoveExtensionRequest {

 /// List all tools available in a session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/tools", response = GetToolsResponse)]
+#[request(method = "_goose/unstable/tools/list", response = GetToolsResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct GetToolsRequest {
    pub session_id: String,
@@ -58,7 +58,7 @@ pub struct GetToolsResponse {

 /// Read a resource from an extension.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/resource/read", response = ReadResourceResponse)]
+#[request(method = "_goose/unstable/resources/read", response = ReadResourceResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ReadResourceRequest {
    pub session_id: String,
@@ -76,7 +76,7 @@ pub struct ReadResourceResponse {

 /// Call a tool from an extension.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/tool/call", response = GooseToolCallResponse)]
+#[request(method = "_goose/unstable/tools/call", response = GooseToolCallResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct GooseToolCallRequest {
    pub session_id: String,
@@ -101,7 +101,7 @@ pub struct GooseToolCallResponse {

 /// Update the working directory for a session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/working_dir/update", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/working-dir/update", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct UpdateWorkingDirRequest {
    pub session_id: String,
@@ -118,7 +118,7 @@ pub struct DeleteSessionRequest {

 /// List configured extensions and any warnings.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/config/extensions", response = GetExtensionsResponse)]
+#[request(method = "_goose/unstable/config/extensions/list", response = GetExtensionsResponse)]
 pub struct GetExtensionsRequest {}

 /// List configured extensions and any warnings.
@@ -131,7 +131,7 @@ pub struct GetExtensionsResponse {

 /// Persist a new extension to the user's global goose config.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/config/extensions/add", response = EmptyResponse)]
+#[request(method = "_goose/unstable/config/extensions/add", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct AddConfigExtensionRequest {
    pub name: String,
@@ -146,7 +146,7 @@ pub struct AddConfigExtensionRequest {

 /// Remove a persisted extension from the user's global goose config.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/config/extensions/remove", response = EmptyResponse)]
+#[request(method = "_goose/unstable/config/extensions/remove", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct RemoveConfigExtensionRequest {
    pub config_key: String,
@@ -154,7 +154,7 @@ pub struct RemoveConfigExtensionRequest {

 /// Toggle the `enabled` flag for a persisted extension in the user's global goose config.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/config/extensions/toggle", response = EmptyResponse)]
+#[request(method = "_goose/unstable/config/extensions/toggle", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ToggleConfigExtensionRequest {
    pub config_key: String,
@@ -162,7 +162,7 @@ pub struct ToggleConfigExtensionRequest {
 }

 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/extensions", response = GetSessionExtensionsResponse)]
+#[request(method = "_goose/unstable/session/extensions/list", response = GetSessionExtensionsResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct GetSessionExtensionsRequest {
    pub session_id: String,
@@ -175,7 +175,7 @@ pub struct GetSessionExtensionsResponse {

 /// Read allowlisted user preferences. Empty `keys` means all supported preferences.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/preferences/read", response = PreferencesReadResponse)]
+#[request(method = "_goose/unstable/preferences/read", response = PreferencesReadResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct PreferencesReadRequest {
    #[serde(default)]
@@ -184,7 +184,7 @@ pub struct PreferencesReadRequest {

 /// Save allowlisted user preferences.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/preferences/save", response = EmptyResponse)]
+#[request(method = "_goose/unstable/preferences/save", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct PreferencesSaveRequest {
    #[serde(default)]
@@ -193,7 +193,7 @@ pub struct PreferencesSaveRequest {

 /// Remove allowlisted user preferences.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/preferences/remove", response = EmptyResponse)]
+#[request(method = "_goose/unstable/preferences/remove", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct PreferencesRemoveRequest {
    #[serde(default)]
@@ -226,7 +226,7 @@ pub struct PreferencesReadResponse {

 /// Read Goose default provider and model configuration.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/defaults/read", response = DefaultsReadResponse)]
+#[request(method = "_goose/unstable/defaults/read", response = DefaultsReadResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DefaultsReadRequest {}

@@ -239,7 +239,7 @@ pub struct DefaultsReadResponse {

 /// Save Goose default provider and model configuration.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/defaults/save", response = DefaultsReadResponse)]
+#[request(method = "_goose/unstable/defaults/save", response = DefaultsReadResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DefaultsSaveRequest {
    pub provider_id: String,
@@ -282,7 +282,7 @@ pub struct OnboardingImportCandidate {
 /// Scan for existing Goose and compatible app data that onboarding can import.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/onboarding/import/scan",
+    method = "_goose/unstable/onboarding/import/scan",
    response = OnboardingImportScanResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -301,7 +301,7 @@ pub struct OnboardingImportScanResponse {
 /// Import selected onboarding candidates.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/onboarding/import/apply",
+    method = "_goose/unstable/onboarding/import/apply",
    response = OnboardingImportApplyResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -325,7 +325,7 @@ pub struct OnboardingImportApplyResponse {

 /// Set a dictation provider secret value.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/secret/save", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/secret/save", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationSecretSaveRequest {
    pub provider: String,
@@ -334,7 +334,7 @@ pub struct DictationSecretSaveRequest {

 /// Remove a dictation provider secret value.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/secret/delete", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/secret/delete", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationSecretDeleteRequest {
    pub provider: String,
@@ -342,7 +342,7 @@ pub struct DictationSecretDeleteRequest {

 /// Update the project association for a session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/update_project", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/project/update", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct UpdateSessionProjectRequest {
    pub session_id: String,
@@ -351,7 +351,7 @@ pub struct UpdateSessionProjectRequest {

 /// Rename a session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/rename", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/rename", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct RenameSessionRequest {
    pub session_id: String,
@@ -360,7 +360,7 @@ pub struct RenameSessionRequest {

 /// Archive a session (soft delete).
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/archive", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/archive", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ArchiveSessionRequest {
    pub session_id: String,
@@ -368,7 +368,7 @@ pub struct ArchiveSessionRequest {

 /// Unarchive a previously archived session.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/unarchive", response = EmptyResponse)]
+#[request(method = "_goose/unstable/session/unarchive", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct UnarchiveSessionRequest {
    pub session_id: String,
@@ -376,7 +376,7 @@ pub struct UnarchiveSessionRequest {

 /// Export a session as a JSON string.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/export", response = ExportSessionResponse)]
+#[request(method = "_goose/unstable/session/export", response = ExportSessionResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ExportSessionRequest {
    pub session_id: String,
@@ -390,7 +390,7 @@ pub struct ExportSessionResponse {

 /// Import a session from a JSON string.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/session/import", response = ImportSessionResponse)]
+#[request(method = "_goose/unstable/session/import", response = ImportSessionResponse)]
 pub struct ImportSessionRequest {
    pub data: String,
 }
@@ -449,7 +449,7 @@ pub struct ProviderConfigFieldUpdate {
 /// Read saved configuration field values for one provider.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/config/read",
+    method = "_goose/unstable/providers/config/read",
    response = ProviderConfigReadResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -466,7 +466,7 @@ pub struct ProviderConfigReadResponse {
 /// Return provider configured statuses. Empty provider_ids means all providers.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/config/status",
+    method = "_goose/unstable/providers/config/status",
    response = ProviderConfigStatusResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -484,7 +484,7 @@ pub struct ProviderConfigStatusResponse {
 /// Save provider configuration fields and start an inventory refresh when supported.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/config/save",
+    method = "_goose/unstable/providers/config/save",
    response = ProviderConfigChangeResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -496,7 +496,7 @@ pub struct ProviderConfigSaveRequest {
 /// Delete provider configuration fields and start an inventory refresh when supported.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/config/delete",
+    method = "_goose/unstable/providers/config/delete",
    response = ProviderConfigChangeResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -507,7 +507,7 @@ pub struct ProviderConfigDeleteRequest {
 /// Run a provider-owned native authentication flow and start an inventory refresh when supported.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/config/authenticate",
+    method = "_goose/unstable/providers/config/authenticate",
    response = ProviderConfigChangeResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -636,7 +636,7 @@ pub struct ProviderTemplateDto {
 /// List custom-provider catalog entries. Omit `format` to list all formats.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/catalog/list",
+    method = "_goose/unstable/providers/catalog/list",
    response = ProviderCatalogListResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -654,7 +654,7 @@ pub struct ProviderCatalogListResponse {
 /// List provider setup catalog entries
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/setup/catalog/list",
+    method = "_goose/unstable/providers/setup/catalog/list",
    response = ProviderSetupCatalogListResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -669,7 +669,7 @@ pub struct ProviderSetupCatalogListResponse {
 /// Return the editable template for one catalog provider.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/catalog/template",
+    method = "_goose/unstable/providers/catalog/template",
    response = ProviderCatalogTemplateResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -733,7 +733,7 @@ pub struct CustomProviderUpsertDto {
 /// Create a custom provider backed by Goose's declarative provider store.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/custom/create",
+    method = "_goose/unstable/providers/custom/create",
    response = CustomProviderCreateResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -753,7 +753,7 @@ pub struct CustomProviderCreateResponse {
 /// Read a declarative provider config. Custom configs are editable; bundled configs are read-only.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/custom/read",
+    method = "_goose/unstable/providers/custom/read",
    response = CustomProviderReadResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -772,7 +772,7 @@ pub struct CustomProviderReadResponse {
 /// Update a custom provider backed by Goose's declarative provider store.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/custom/update",
+    method = "_goose/unstable/providers/custom/update",
    response = CustomProviderUpdateResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -793,7 +793,7 @@ pub struct CustomProviderUpdateResponse {
 /// Delete a custom provider from Goose's declarative provider store.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/custom/delete",
+    method = "_goose/unstable/providers/custom/delete",
    response = CustomProviderDeleteResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -881,9 +881,25 @@ impl SourceEntry {
    }
 }

+/// Target scope for creating or importing sources.
+#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "scope", rename_all = "camelCase")]
+pub enum SourceScope {
+    #[default]
+    Global,
+    ProjectDir {
+        #[serde(rename = "projectDir")]
+        project_dir: String,
+    },
+    ProjectId {
+        #[serde(rename = "projectId")]
+        project_id: String,
+    },
+}
+
 /// Create a new source in an explicit target scope (global or project-scoped).
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/create", response = CreateSourceResponse)]
+#[request(method = "_goose/unstable/sources/create", response = CreateSourceResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct CreateSourceRequest {
    #[serde(rename = "type")]
@@ -891,15 +907,7 @@ pub struct CreateSourceRequest {
    pub name: String,
    pub description: String,
    pub content: String,
-    pub global: bool,
-    /// Absolute path to the project root. Required when `global` is false.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_dir: Option<String>,
-    /// Project source ID. When set with `global: false`, the backend resolves
-    /// the project's first working directory automatically. Takes precedence
-    /// over `project_dir`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_id: Option<String>,
+    pub target: SourceScope,
    /// Arbitrary key/value metadata.
    #[serde(default, skip_serializing_if = "std::collections::HashMap::is_empty")]
    pub properties: std::collections::HashMap<String, serde_json::Value>,
@@ -918,7 +926,7 @@ pub struct CreateSourceResponse {
 /// set. If `type` is `builtinSkill`, this lists shipped read-only built-in
 /// skills.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/list", response = ListSourcesResponse)]
+#[request(method = "_goose/unstable/sources/list", response = ListSourcesResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ListSourcesRequest {
    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
@@ -939,7 +947,7 @@ pub struct ListSourcesResponse {

 /// Update an existing source's name, description, and content by absolute path.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/update", response = UpdateSourceResponse)]
+#[request(method = "_goose/unstable/sources/update", response = UpdateSourceResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct UpdateSourceRequest {
    #[serde(rename = "type")]
@@ -965,7 +973,7 @@ pub struct UpdateSourceResponse {

 /// Delete a source and its on-disk directory by absolute path.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/delete", response = EmptyResponse)]
+#[request(method = "_goose/unstable/sources/delete", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DeleteSourceRequest {
    #[serde(rename = "type")]
@@ -975,7 +983,7 @@ pub struct DeleteSourceRequest {

 /// Export a source at an absolute path as a portable JSON payload.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/export", response = ExportSourceResponse)]
+#[request(method = "_goose/unstable/sources/export", response = ExportSourceResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ExportSourceRequest {
    #[serde(rename = "type")]
@@ -990,17 +998,15 @@ pub struct ExportSourceResponse {
    pub filename: String,
 }

-/// Import a source from a JSON export payload produced by `_goose/sources/export`.
+/// Import a source from a JSON export payload produced by `_goose/unstable/sources/export`.
 /// The imported source is written into the explicit target scope; on name
 /// collisions a `-imported` suffix is appended.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/sources/import", response = ImportSourcesResponse)]
+#[request(method = "_goose/unstable/sources/import", response = ImportSourcesResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ImportSourcesRequest {
    pub data: String,
-    pub global: bool,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub project_dir: Option<String>,
+    pub target: SourceScope,
 }

 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcResponse)]
@@ -1011,7 +1017,7 @@ pub struct ImportSourcesResponse {

 /// Transcribe audio via a dictation provider.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/transcribe", response = DictationTranscribeResponse)]
+#[request(method = "_goose/unstable/dictation/transcribe", response = DictationTranscribeResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationTranscribeRequest {
    /// Base64-encoded audio data
@@ -1030,7 +1036,7 @@ pub struct DictationTranscribeResponse {

 /// Get the configuration status of all dictation providers.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/config", response = DictationConfigResponse)]
+#[request(method = "_goose/unstable/dictation/config", response = DictationConfigResponse)]
 pub struct DictationConfigRequest {}

 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema)]
@@ -1071,7 +1077,7 @@ pub struct DictationConfigResponse {

 /// List providers with setup metadata and the current model inventory snapshot.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/providers/list", response = ListProvidersResponse)]
+#[request(method = "_goose/unstable/providers/list", response = ListProvidersResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct ListProvidersRequest {
    /// Only return entries for these providers. Empty means all.
@@ -1088,7 +1094,7 @@ pub struct ListProvidersResponse {
 /// Trigger a background refresh of provider inventories.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/providers/inventory/refresh",
+    method = "_goose/unstable/providers/inventory/refresh",
    response = RefreshProviderInventoryResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -1199,7 +1205,7 @@ pub struct EmptyResponse {}
 /// List available local Whisper models with their download status.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/dictation/models/list",
+    method = "_goose/unstable/dictation/models/list",
    response = DictationModelsListResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -1224,7 +1230,7 @@ pub struct DictationLocalModelStatus {

 /// Kick off a background download of a local Whisper model.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/models/download", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/models/download", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationModelDownloadRequest {
    pub model_id: String,
@@ -1233,7 +1239,7 @@ pub struct DictationModelDownloadRequest {
 /// Poll the progress of an in-flight download.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
 #[request(
-    method = "_goose/dictation/models/download/progress",
+    method = "_goose/unstable/dictation/models/download/progress",
    response = DictationModelDownloadProgressResponse
 )]
 #[serde(rename_all = "camelCase")]
@@ -1261,7 +1267,7 @@ pub struct DictationDownloadProgress {

 /// Cancel an in-flight download.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/models/cancel", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/models/cancel", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationModelCancelRequest {
    pub model_id: String,
@@ -1269,7 +1275,7 @@ pub struct DictationModelCancelRequest {

 /// Delete a downloaded local Whisper model from disk.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/models/delete", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/models/delete", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationModelDeleteRequest {
    pub model_id: String,
@@ -1277,7 +1283,7 @@ pub struct DictationModelDeleteRequest {

 /// Persist the user's model selection for a given provider.
 #[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema, JsonRpcRequest)]
-#[request(method = "_goose/dictation/model/select", response = EmptyResponse)]
+#[request(method = "_goose/unstable/dictation/models/select", response = EmptyResponse)]
 #[serde(rename_all = "camelCase")]
 pub struct DictationModelSelectRequest {
    pub provider: String,
@@ -1,33 +1,33 @@
 {
  "methods": [
    {
-      "method": "_goose/extensions/add",
-      "requestType": "AddExtensionRequest",
+      "method": "_goose/unstable/session/extensions/add",
+      "requestType": "AddExtensionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/extensions/remove",
-      "requestType": "RemoveExtensionRequest",
+      "method": "_goose/unstable/session/extensions/remove",
+      "requestType": "RemoveExtensionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/tools",
-      "requestType": "GetToolsRequest",
-      "responseType": "GetToolsResponse"
+      "method": "_goose/unstable/tools/list",
+      "requestType": "GetToolsRequest_unstable",
+      "responseType": "GetToolsResponse_unstable"
    },
    {
-      "method": "_goose/tool/call",
-      "requestType": "GooseToolCallRequest",
-      "responseType": "GooseToolCallResponse"
+      "method": "_goose/unstable/tools/call",
+      "requestType": "GooseToolCallRequest_unstable",
+      "responseType": "GooseToolCallResponse_unstable"
    },
    {
-      "method": "_goose/resource/read",
-      "requestType": "ReadResourceRequest",
-      "responseType": "ReadResourceResponse"
+      "method": "_goose/unstable/resources/read",
+      "requestType": "ReadResourceRequest_unstable",
+      "responseType": "ReadResourceResponse_unstable"
    },
    {
-      "method": "_goose/working_dir/update",
-      "requestType": "UpdateWorkingDirRequest",
+      "method": "_goose/unstable/session/working-dir/update",
+      "requestType": "UpdateWorkingDirRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
@@ -36,243 +36,243 @@
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/config/extensions",
-      "requestType": "GetExtensionsRequest",
-      "responseType": "GetExtensionsResponse"
+      "method": "_goose/unstable/config/extensions/list",
+      "requestType": "GetExtensionsRequest_unstable",
+      "responseType": "GetExtensionsResponse_unstable"
    },
    {
-      "method": "_goose/config/extensions/add",
-      "requestType": "AddConfigExtensionRequest",
+      "method": "_goose/unstable/config/extensions/add",
+      "requestType": "AddConfigExtensionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/config/extensions/remove",
-      "requestType": "RemoveConfigExtensionRequest",
+      "method": "_goose/unstable/config/extensions/remove",
+      "requestType": "RemoveConfigExtensionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/config/extensions/toggle",
-      "requestType": "ToggleConfigExtensionRequest",
+      "method": "_goose/unstable/config/extensions/toggle",
+      "requestType": "ToggleConfigExtensionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/session/extensions",
-      "requestType": "GetSessionExtensionsRequest",
-      "responseType": "GetSessionExtensionsResponse"
+      "method": "_goose/unstable/session/extensions/list",
+      "requestType": "GetSessionExtensionsRequest_unstable",
+      "responseType": "GetSessionExtensionsResponse_unstable"
    },
    {
-      "method": "_goose/providers/list",
-      "requestType": "ListProvidersRequest",
-      "responseType": "ListProvidersResponse"
+      "method": "_goose/unstable/providers/list",
+      "requestType": "ListProvidersRequest_unstable",
+      "responseType": "ListProvidersResponse_unstable"
    },
    {
-      "method": "_goose/providers/catalog/list",
-      "requestType": "ProviderCatalogListRequest",
-      "responseType": "ProviderCatalogListResponse"
+      "method": "_goose/unstable/providers/catalog/list",
+      "requestType": "ProviderCatalogListRequest_unstable",
+      "responseType": "ProviderCatalogListResponse_unstable"
    },
    {
-      "method": "_goose/providers/setup/catalog/list",
-      "requestType": "ProviderSetupCatalogListRequest",
-      "responseType": "ProviderSetupCatalogListResponse"
+      "method": "_goose/unstable/providers/setup/catalog/list",
+      "requestType": "ProviderSetupCatalogListRequest_unstable",
+      "responseType": "ProviderSetupCatalogListResponse_unstable"
    },
    {
-      "method": "_goose/providers/catalog/template",
-      "requestType": "ProviderCatalogTemplateRequest",
-      "responseType": "ProviderCatalogTemplateResponse"
+      "method": "_goose/unstable/providers/catalog/template",
+      "requestType": "ProviderCatalogTemplateRequest_unstable",
+      "responseType": "ProviderCatalogTemplateResponse_unstable"
    },
    {
-      "method": "_goose/providers/custom/create",
-      "requestType": "CustomProviderCreateRequest",
-      "responseType": "CustomProviderCreateResponse"
+      "method": "_goose/unstable/providers/custom/create",
+      "requestType": "CustomProviderCreateRequest_unstable",
+      "responseType": "CustomProviderCreateResponse_unstable"
    },
    {
-      "method": "_goose/providers/custom/read",
-      "requestType": "CustomProviderReadRequest",
-      "responseType": "CustomProviderReadResponse"
+      "method": "_goose/unstable/providers/custom/read",
+      "requestType": "CustomProviderReadRequest_unstable",
+      "responseType": "CustomProviderReadResponse_unstable"
    },
    {
-      "method": "_goose/providers/custom/update",
-      "requestType": "CustomProviderUpdateRequest",
-      "responseType": "CustomProviderUpdateResponse"
+      "method": "_goose/unstable/providers/custom/update",
+      "requestType": "CustomProviderUpdateRequest_unstable",
+      "responseType": "CustomProviderUpdateResponse_unstable"
    },
    {
-      "method": "_goose/providers/custom/delete",
-      "requestType": "CustomProviderDeleteRequest",
-      "responseType": "CustomProviderDeleteResponse"
+      "method": "_goose/unstable/providers/custom/delete",
+      "requestType": "CustomProviderDeleteRequest_unstable",
+      "responseType": "CustomProviderDeleteResponse_unstable"
    },
    {
-      "method": "_goose/providers/inventory/refresh",
-      "requestType": "RefreshProviderInventoryRequest",
-      "responseType": "RefreshProviderInventoryResponse"
+      "method": "_goose/unstable/providers/inventory/refresh",
+      "requestType": "RefreshProviderInventoryRequest_unstable",
+      "responseType": "RefreshProviderInventoryResponse_unstable"
    },
    {
-      "method": "_goose/providers/config/read",
-      "requestType": "ProviderConfigReadRequest",
-      "responseType": "ProviderConfigReadResponse"
+      "method": "_goose/unstable/providers/config/read",
+      "requestType": "ProviderConfigReadRequest_unstable",
+      "responseType": "ProviderConfigReadResponse_unstable"
    },
    {
-      "method": "_goose/providers/config/status",
-      "requestType": "ProviderConfigStatusRequest",
-      "responseType": "ProviderConfigStatusResponse"
+      "method": "_goose/unstable/providers/config/status",
+      "requestType": "ProviderConfigStatusRequest_unstable",
+      "responseType": "ProviderConfigStatusResponse_unstable"
    },
    {
-      "method": "_goose/providers/config/save",
-      "requestType": "ProviderConfigSaveRequest",
-      "responseType": "ProviderConfigChangeResponse"
+      "method": "_goose/unstable/providers/config/save",
+      "requestType": "ProviderConfigSaveRequest_unstable",
+      "responseType": "ProviderConfigChangeResponse_unstable"
    },
    {
-      "method": "_goose/providers/config/delete",
-      "requestType": "ProviderConfigDeleteRequest",
-      "responseType": "ProviderConfigChangeResponse"
+      "method": "_goose/unstable/providers/config/delete",
+      "requestType": "ProviderConfigDeleteRequest_unstable",
+      "responseType": "ProviderConfigChangeResponse_unstable"
    },
    {
-      "method": "_goose/providers/config/authenticate",
-      "requestType": "ProviderConfigAuthenticateRequest",
-      "responseType": "ProviderConfigChangeResponse"
+      "method": "_goose/unstable/providers/config/authenticate",
+      "requestType": "ProviderConfigAuthenticateRequest_unstable",
+      "responseType": "ProviderConfigChangeResponse_unstable"
    },
    {
-      "method": "_goose/preferences/read",
-      "requestType": "PreferencesReadRequest",
-      "responseType": "PreferencesReadResponse"
+      "method": "_goose/unstable/preferences/read",
+      "requestType": "PreferencesReadRequest_unstable",
+      "responseType": "PreferencesReadResponse_unstable"
    },
    {
-      "method": "_goose/preferences/save",
-      "requestType": "PreferencesSaveRequest",
+      "method": "_goose/unstable/preferences/save",
+      "requestType": "PreferencesSaveRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/preferences/remove",
-      "requestType": "PreferencesRemoveRequest",
+      "method": "_goose/unstable/preferences/remove",
+      "requestType": "PreferencesRemoveRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/defaults/read",
-      "requestType": "DefaultsReadRequest",
-      "responseType": "DefaultsReadResponse"
+      "method": "_goose/unstable/defaults/read",
+      "requestType": "DefaultsReadRequest_unstable",
+      "responseType": "DefaultsReadResponse_unstable"
    },
    {
-      "method": "_goose/defaults/save",
-      "requestType": "DefaultsSaveRequest",
-      "responseType": "DefaultsReadResponse"
+      "method": "_goose/unstable/defaults/save",
+      "requestType": "DefaultsSaveRequest_unstable",
+      "responseType": "DefaultsReadResponse_unstable"
    },
    {
-      "method": "_goose/onboarding/import/scan",
-      "requestType": "OnboardingImportScanRequest",
-      "responseType": "OnboardingImportScanResponse"
+      "method": "_goose/unstable/onboarding/import/scan",
+      "requestType": "OnboardingImportScanRequest_unstable",
+      "responseType": "OnboardingImportScanResponse_unstable"
    },
    {
-      "method": "_goose/onboarding/import/apply",
-      "requestType": "OnboardingImportApplyRequest",
-      "responseType": "OnboardingImportApplyResponse"
+      "method": "_goose/unstable/onboarding/import/apply",
+      "requestType": "OnboardingImportApplyRequest_unstable",
+      "responseType": "OnboardingImportApplyResponse_unstable"
    },
    {
-      "method": "_goose/session/export",
-      "requestType": "ExportSessionRequest",
-      "responseType": "ExportSessionResponse"
+      "method": "_goose/unstable/session/export",
+      "requestType": "ExportSessionRequest_unstable",
+      "responseType": "ExportSessionResponse_unstable"
    },
    {
-      "method": "_goose/session/import",
-      "requestType": "ImportSessionRequest",
-      "responseType": "ImportSessionResponse"
+      "method": "_goose/unstable/session/import",
+      "requestType": "ImportSessionRequest_unstable",
+      "responseType": "ImportSessionResponse_unstable"
    },
    {
-      "method": "_goose/session/update_project",
-      "requestType": "UpdateSessionProjectRequest",
+      "method": "_goose/unstable/session/project/update",
+      "requestType": "UpdateSessionProjectRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/session/rename",
-      "requestType": "RenameSessionRequest",
+      "method": "_goose/unstable/session/rename",
+      "requestType": "RenameSessionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/session/archive",
-      "requestType": "ArchiveSessionRequest",
+      "method": "_goose/unstable/session/archive",
+      "requestType": "ArchiveSessionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/session/unarchive",
-      "requestType": "UnarchiveSessionRequest",
+      "method": "_goose/unstable/session/unarchive",
+      "requestType": "UnarchiveSessionRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/sources/create",
-      "requestType": "CreateSourceRequest",
-      "responseType": "CreateSourceResponse"
+      "method": "_goose/unstable/sources/create",
+      "requestType": "CreateSourceRequest_unstable",
+      "responseType": "CreateSourceResponse_unstable"
    },
    {
-      "method": "_goose/sources/list",
-      "requestType": "ListSourcesRequest",
-      "responseType": "ListSourcesResponse"
+      "method": "_goose/unstable/sources/list",
+      "requestType": "ListSourcesRequest_unstable",
+      "responseType": "ListSourcesResponse_unstable"
    },
    {
-      "method": "_goose/sources/update",
-      "requestType": "UpdateSourceRequest",
-      "responseType": "UpdateSourceResponse"
+      "method": "_goose/unstable/sources/update",
+      "requestType": "UpdateSourceRequest_unstable",
+      "responseType": "UpdateSourceResponse_unstable"
    },
    {
-      "method": "_goose/sources/delete",
-      "requestType": "DeleteSourceRequest",
+      "method": "_goose/unstable/sources/delete",
+      "requestType": "DeleteSourceRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/sources/export",
-      "requestType": "ExportSourceRequest",
-      "responseType": "ExportSourceResponse"
+      "method": "_goose/unstable/sources/export",
+      "requestType": "ExportSourceRequest_unstable",
+      "responseType": "ExportSourceResponse_unstable"
    },
    {
-      "method": "_goose/sources/import",
-      "requestType": "ImportSourcesRequest",
-      "responseType": "ImportSourcesResponse"
+      "method": "_goose/unstable/sources/import",
+      "requestType": "ImportSourcesRequest_unstable",
+      "responseType": "ImportSourcesResponse_unstable"
    },
    {
-      "method": "_goose/dictation/transcribe",
-      "requestType": "DictationTranscribeRequest",
-      "responseType": "DictationTranscribeResponse"
+      "method": "_goose/unstable/dictation/transcribe",
+      "requestType": "DictationTranscribeRequest_unstable",
+      "responseType": "DictationTranscribeResponse_unstable"
    },
    {
-      "method": "_goose/dictation/config",
-      "requestType": "DictationConfigRequest",
-      "responseType": "DictationConfigResponse"
+      "method": "_goose/unstable/dictation/config",
+      "requestType": "DictationConfigRequest_unstable",
+      "responseType": "DictationConfigResponse_unstable"
    },
    {
-      "method": "_goose/dictation/secret/save",
-      "requestType": "DictationSecretSaveRequest",
+      "method": "_goose/unstable/dictation/secret/save",
+      "requestType": "DictationSecretSaveRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/dictation/secret/delete",
-      "requestType": "DictationSecretDeleteRequest",
+      "method": "_goose/unstable/dictation/secret/delete",
+      "requestType": "DictationSecretDeleteRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/dictation/models/list",
-      "requestType": "DictationModelsListRequest",
-      "responseType": "DictationModelsListResponse"
+      "method": "_goose/unstable/dictation/models/list",
+      "requestType": "DictationModelsListRequest_unstable",
+      "responseType": "DictationModelsListResponse_unstable"
    },
    {
-      "method": "_goose/dictation/models/download",
-      "requestType": "DictationModelDownloadRequest",
+      "method": "_goose/unstable/dictation/models/download",
+      "requestType": "DictationModelDownloadRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/dictation/models/download/progress",
-      "requestType": "DictationModelDownloadProgressRequest",
-      "responseType": "DictationModelDownloadProgressResponse"
+      "method": "_goose/unstable/dictation/models/download/progress",
+      "requestType": "DictationModelDownloadProgressRequest_unstable",
+      "responseType": "DictationModelDownloadProgressResponse_unstable"
    },
    {
-      "method": "_goose/dictation/models/cancel",
-      "requestType": "DictationModelCancelRequest",
+      "method": "_goose/unstable/dictation/models/cancel",
+      "requestType": "DictationModelCancelRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/dictation/models/delete",
-      "requestType": "DictationModelDeleteRequest",
+      "method": "_goose/unstable/dictation/models/delete",
+      "requestType": "DictationModelDeleteRequest_unstable",
      "responseType": "EmptyResponse"
    },
    {
-      "method": "_goose/dictation/model/select",
-      "requestType": "DictationModelSelectRequest",
+      "method": "_goose/unstable/dictation/models/select",
+      "requestType": "DictationModelSelectRequest_unstable",
      "responseType": "EmptyResponse"
    }
  ]
@@ -5,24 +5,13 @@ impl GooseAcpAgent {
        &self,
        req: CreateSourceRequest,
    ) -> Result<CreateSourceResponse, agent_client_protocol::Error> {
-        let project_dir = match (&req.project_id, &req.project_dir) {
-            (Some(pid), _) if !req.global => {
-                let dirs = crate::sources::project_working_dirs(pid);
-                Some(dirs.into_iter().next().ok_or_else(|| {
-                    agent_client_protocol::Error::invalid_params().data(format!(
-                        "Project \"{pid}\" has no working directories configured"
-                    ))
-                })?)
-            }
-            (_, Some(pd)) => Some(pd.clone()),
-            _ => None,
-        };
+        let (global, project_dir) = resolve_source_scope(&req.target)?;
        let source = crate::sources::create_source(
            req.source_type,
            &req.name,
            &req.description,
            &req.content,
-            req.global,
+            global,
            project_dir.as_deref(),
            req.properties,
        )?;
@@ -88,8 +77,26 @@ impl GooseAcpAgent {
        &self,
        req: ImportSourcesRequest,
    ) -> Result<ImportSourcesResponse, agent_client_protocol::Error> {
-        let sources =
-            crate::sources::import_sources(&req.data, req.global, req.project_dir.as_deref())?;
+        let (global, project_dir) = resolve_source_scope(&req.target)?;
+        let sources = crate::sources::import_sources(&req.data, global, project_dir.as_deref())?;
        Ok(ImportSourcesResponse { sources })
    }
 }
+
+fn resolve_source_scope(
+    target: &SourceScope,
+) -> Result<(bool, Option<String>), agent_client_protocol::Error> {
+    match target {
+        SourceScope::Global => Ok((true, None)),
+        SourceScope::ProjectDir { project_dir } => Ok((false, Some(project_dir.clone()))),
+        SourceScope::ProjectId { project_id } => {
+            let dirs = crate::sources::project_working_dirs(project_id);
+            let project_dir = dirs.into_iter().next().ok_or_else(|| {
+                agent_client_protocol::Error::invalid_params().data(format!(
+                    "Project \"{project_id}\" has no working directories configured"
+                ))
+            })?;
+            Ok((false, Some(project_dir)))
+        }
+    }
+}
@@ -35,6 +35,32 @@ fn main() {
        }
    }

+    let unstable_type_names: BTreeSet<String> = type_methods
+        .iter()
+        .filter_map(|(name, methods_list)| {
+            if methods_list.iter().all(|method| is_unstable_method(method)) {
+                Some(name.clone())
+            } else {
+                None
+            }
+        })
+        .collect();
+
+    for def in defs.values_mut() {
+        rewrite_unstable_schema_refs(def, &unstable_type_names);
+    }
+
+    let mut renamed_defs = Map::new();
+    for (name, def) in defs {
+        let generated_name = generated_type_name(&name, &unstable_type_names);
+        let previous = renamed_defs.insert(generated_name.clone(), def);
+        assert!(
+            previous.is_none(),
+            "duplicate schema definition name after unstable suffix: {generated_name}"
+        );
+    }
+    let mut defs = renamed_defs;
+
    // Replace `true` with `{}` throughout $defs. Both mean "accept any value" in
    // JSON Schema, but many TS codegen tools (e.g. @hey-api/openapi-ts Zod plugin)
    // silently drop properties whose schema is the bare `true` literal.
@@ -49,7 +75,8 @@ fn main() {
    // Annotate $defs entries with x-method/x-side. Only set x-method for types
    // used by exactly one method (shared types like EmptyResponse skip x-method).
    for (name, methods_list) in &type_methods {
-        if let Some(def) = defs.get_mut(name) {
+        let generated_name = generated_type_name(name, &unstable_type_names);
+        if let Some(def) = defs.get_mut(&generated_name) {
            if let Some(obj) = def.as_object_mut() {
                obj.insert("x-side".into(), json!("agent"));
                if methods_list.len() == 1 {
@@ -67,18 +94,20 @@ fn main() {

    for m in &methods {
        if let Some(name) = &m.params_type_name {
+            let generated_name = generated_type_name(name, &unstable_type_names);
            request_variants.push(json!({
-                "allOf": [{ "$ref": format!("#/$defs/{name}") }],
+                "allOf": [{ "$ref": format!("#/$defs/{generated_name}") }],
                "description": format!("Params for {}", m.method),
-                "title": name,
+                "title": generated_name,
            }));
        }

        if let Some(name) = &m.response_type_name {
-            if seen_response_types.insert(name.clone()) {
+            let generated_name = generated_type_name(name, &unstable_type_names);
+            if seen_response_types.insert(generated_name.clone()) {
                response_variants.push(json!({
-                    "allOf": [{ "$ref": format!("#/$defs/{name}") }],
-                    "title": name,
+                    "allOf": [{ "$ref": format!("#/$defs/{generated_name}") }],
+                    "title": generated_name,
                }));
            }
        }
@@ -179,8 +208,14 @@ fn main() {
        .map(|m| {
            json!({
                "method": &m.method,
-                "requestType": m.params_type_name,
-                "responseType": m.response_type_name,
+                "requestType": m
+                    .params_type_name
+                    .as_ref()
+                    .map(|name| generated_type_name(name, &unstable_type_names)),
+                "responseType": m
+                    .response_type_name
+                    .as_ref()
+                    .map(|name| generated_type_name(name, &unstable_type_names)),
            })
        })
        .collect();
@@ -193,6 +228,41 @@ fn main() {
    println!("{json_str}");
 }

+fn is_unstable_method(method: &str) -> bool {
+    method.contains("_goose/unstable")
+}
+
+fn generated_type_name(name: &str, unstable_type_names: &BTreeSet<String>) -> String {
+    if unstable_type_names.contains(name) {
+        format!("{name}_unstable")
+    } else {
+        name.to_string()
+    }
+}
+
+fn rewrite_unstable_schema_refs(value: &mut Value, unstable_type_names: &BTreeSet<String>) {
+    match value {
+        Value::Object(map) => {
+            if let Some(Value::String(reference)) = map.get_mut("$ref") {
+                if let Some(name) = reference.strip_prefix("#/$defs/") {
+                    if unstable_type_names.contains(name) {
+                        *reference = format!("#/$defs/{name}_unstable");
+                    }
+                }
+            }
+            for v in map.values_mut() {
+                rewrite_unstable_schema_refs(v, unstable_type_names);
+            }
+        }
+        Value::Array(arr) => {
+            for v in arr.iter_mut() {
+                rewrite_unstable_schema_refs(v, unstable_type_names);
+            }
+        }
+        _ => {}
+    }
+}
+
 /// Recursively strip `"format"` from integer-typed schemas.
 ///
 /// schemars emits `"format": "uint64"` / `"int64"` etc. for Rust integer types.
@@ -56,7 +56,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let catalog = send_custom(
            conn.cx(),
-            "_goose/providers/catalog/list",
+            "_goose/unstable/providers/catalog/list",
            serde_json::json!({ "format": "openai" }),
        )
        .await
@@ -74,7 +74,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let setup_catalog = send_custom(
            conn.cx(),
-            "_goose/providers/setup/catalog/list",
+            "_goose/unstable/providers/setup/catalog/list",
            serde_json::json!({}),
        )
        .await
@@ -137,7 +137,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let template = send_custom(
            conn.cx(),
-            "_goose/providers/catalog/template",
+            "_goose/unstable/providers/catalog/template",
            serde_json::json!({ "providerId": "zai" }),
        )
        .await
@@ -156,7 +156,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let configured_status = send_custom(
            conn.cx(),
-            "_goose/providers/config/status",
+            "_goose/unstable/providers/config/status",
            serde_json::json!({ "providerIds": ["xai"] }),
        )
        .await
@@ -172,7 +172,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let configured_read = send_custom(
            conn.cx(),
-            "_goose/providers/config/read",
+            "_goose/unstable/providers/config/read",
            serde_json::json!({ "providerId": "xai" }),
        )
        .await
@@ -194,7 +194,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let non_oauth_auth = send_custom(
            conn.cx(),
-            "_goose/providers/config/authenticate",
+            "_goose/unstable/providers/config/authenticate",
            serde_json::json!({ "providerId": "xai" }),
        )
        .await;
@@ -210,7 +210,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let created = send_custom(
            conn.cx(),
-            "_goose/providers/custom/create",
+            "_goose/unstable/providers/custom/create",
            serde_json::json!({
                "engine": "openai_compatible",
                "displayName": "Stark ACP Provider",
@@ -292,7 +292,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let read = send_custom(
            conn.cx(),
-            "_goose/providers/custom/read",
+            "_goose/unstable/providers/custom/read",
            serde_json::json!({ "providerId": provider_id }),
        )
        .await
@@ -321,7 +321,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let inventory = send_custom(
            conn.cx(),
-            "_goose/providers/list",
+            "_goose/unstable/providers/list",
            serde_json::json!({ "providerIds": [provider_id] }),
        )
        .await
@@ -337,7 +337,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let updated = send_custom(
            conn.cx(),
-            "_goose/providers/custom/update",
+            "_goose/unstable/providers/custom/update",
            serde_json::json!({
                "providerId": provider_id,
                "engine": "openai",
@@ -392,7 +392,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let auth_disabled = send_custom(
            conn.cx(),
-            "_goose/providers/custom/update",
+            "_goose/unstable/providers/custom/update",
            serde_json::json!({
                "providerId": provider_id,
                "engine": "openai_compatible",
@@ -432,7 +432,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let auth_reenabled_without_key = send_custom(
            conn.cx(),
-            "_goose/providers/custom/update",
+            "_goose/unstable/providers/custom/update",
            serde_json::json!({
                "providerId": provider_id,
                "engine": "openai_compatible",
@@ -464,7 +464,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let deleted = send_custom(
            conn.cx(),
-            "_goose/providers/custom/delete",
+            "_goose/unstable/providers/custom/delete",
            serde_json::json!({ "providerId": provider_id }),
        )
        .await
@@ -494,7 +494,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let deleted_status = send_custom(
            conn.cx(),
-            "_goose/providers/config/status",
+            "_goose/unstable/providers/config/status",
            serde_json::json!({ "providerIds": [provider_id] }),
        )
        .await
@@ -518,7 +518,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {
        ] {
            let read = send_custom(
                conn.cx(),
-                "_goose/providers/custom/read",
+                "_goose/unstable/providers/custom/read",
                serde_json::json!({ "providerId": invalid_id }),
            )
            .await;
@@ -570,7 +570,12 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {
                payload_obj.insert(key.clone(), value.clone());
            }

-            let result = send_custom(conn.cx(), "_goose/providers/custom/create", payload).await;
+            let result = send_custom(
+                conn.cx(),
+                "_goose/unstable/providers/custom/create",
+                payload,
+            )
+            .await;
            assert!(result.is_err(), "{name} should be rejected");
        }

@@ -580,7 +585,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let shared = send_custom(
            conn.cx(),
-            "_goose/providers/custom/create",
+            "_goose/unstable/providers/custom/create",
            serde_json::json!({
                "engine": "openai_compatible",
                "displayName": "Shared Secret Test",
@@ -613,7 +618,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        send_custom(
            conn.cx(),
-            "_goose/providers/custom/update",
+            "_goose/unstable/providers/custom/update",
            serde_json::json!({
                "providerId": shared_id,
                "engine": "openai_compatible",
@@ -635,7 +640,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        let shared_delete = send_custom(
            conn.cx(),
-            "_goose/providers/custom/create",
+            "_goose/unstable/providers/custom/create",
            serde_json::json!({
                "engine": "openai_compatible",
                "displayName": "Shared Secret Delete",
@@ -668,7 +673,7 @@ fn acp_catalog_and_custom_provider_methods_use_core_provider_store() {

        send_custom(
            conn.cx(),
-            "_goose/providers/custom/delete",
+            "_goose/unstable/providers/custom/delete",
            serde_json::json!({ "providerId": shared_delete_id }),
        )
        .await
@@ -79,7 +79,7 @@ fn test_custom_get_tools() {

        let result = send_custom(
            conn.cx(),
-            "_goose/tools",
+            "_goose/unstable/tools/list",
            serde_json::json!({ "sessionId": session_id }),
        )
        .await;
@@ -97,8 +97,12 @@ fn test_custom_get_extensions() {
        let openai = OpenAiFixture::new(vec![], Arc::new(EnforceSessionId::default())).await;
        let conn = AcpServerConnection::new(TestConnectionConfig::default(), openai).await;

-        let result =
-            send_custom(conn.cx(), "_goose/config/extensions", serde_json::json!({})).await;
+        let result = send_custom(
+            conn.cx(),
+            "_goose/unstable/config/extensions/list",
+            serde_json::json!({}),
+        )
+        .await;
        assert!(result.is_ok(), "expected ok, got: {:?}", result);

        let response = result.unwrap();
@@ -221,7 +225,7 @@ fn test_custom_list_builtin_skill_sources() {

        let response = send_custom(
            conn.cx(),
-            "_goose/sources/list",
+            "_goose/unstable/sources/list",
            serde_json::json!({ "type": "builtinSkill" }),
        )
        .await
@@ -253,9 +257,13 @@ fn test_custom_provider_inventory_includes_metadata() {
        let openai = OpenAiFixture::new(vec![], Arc::new(EnforceSessionId::default())).await;
        let conn = AcpServerConnection::new(TestConnectionConfig::default(), openai).await;

-        let response = send_custom(conn.cx(), "_goose/providers/list", serde_json::json!({}))
-            .await
-            .expect("provider inventory should succeed");
+        let response = send_custom(
+            conn.cx(),
+            "_goose/unstable/providers/list",
+            serde_json::json!({}),
+        )
+        .await
+        .expect("provider inventory should succeed");
        let providers = response
            .get("entries")
            .and_then(|value| value.as_array())
@@ -294,7 +302,7 @@ fn test_custom_preferences_read_save_remove() {

        let response = send_custom(
            conn.cx(),
-            "_goose/preferences/read",
+            "_goose/unstable/preferences/read",
            serde_json::json!({
                "keys": [
                    "autoCompactThreshold",
@@ -316,7 +324,7 @@ fn test_custom_preferences_read_save_remove() {

        send_custom(
            conn.cx(),
-            "_goose/preferences/save",
+            "_goose/unstable/preferences/save",
            serde_json::json!({
                "values": [
                    { "key": "voiceDictationProvider", "value": "__disabled__" },
@@ -329,7 +337,7 @@ fn test_custom_preferences_read_save_remove() {

        send_custom(
            conn.cx(),
-            "_goose/preferences/remove",
+            "_goose/unstable/preferences/remove",
            serde_json::json!({
                "keys": ["voiceDictationProvider"],
            }),
@@ -339,7 +347,7 @@ fn test_custom_preferences_read_save_remove() {

        let response = send_custom(
            conn.cx(),
-            "_goose/preferences/read",
+            "_goose/unstable/preferences/read",
            serde_json::json!({
                "keys": ["voiceDictationProvider", "voiceDictationPreferredMic"],
            }),
@@ -381,13 +389,13 @@ fn test_custom_preferences_save_rejects_invalid_values() {
        ];

        for payload in invalid_payloads {
-            let result = send_custom(conn.cx(), "_goose/preferences/save", payload).await;
+            let result = send_custom(conn.cx(), "_goose/unstable/preferences/save", payload).await;
            assert!(result.is_err(), "expected invalid params error");
        }

        let result = send_custom(
            conn.cx(),
-            "_goose/preferences/save",
+            "_goose/unstable/preferences/save",
            serde_json::json!({
                "values": [
                    { "key": "voiceDictationPreferredMic", "value": "mic-1" },
@@ -400,7 +408,7 @@ fn test_custom_preferences_save_rejects_invalid_values() {

        let response = send_custom(
            conn.cx(),
-            "_goose/preferences/read",
+            "_goose/unstable/preferences/read",
            serde_json::json!({
                "keys": ["voiceDictationPreferredMic"],
            }),
@@ -432,9 +440,13 @@ fn test_custom_defaults_read() {
        };
        let conn = AcpServerConnection::new(config, openai).await;

-        let response = send_custom(conn.cx(), "_goose/defaults/read", serde_json::json!({}))
-            .await
-            .expect("defaults read should succeed");
+        let response = send_custom(
+            conn.cx(),
+            "_goose/unstable/defaults/read",
+            serde_json::json!({}),
+        )
+        .await
+        .expect("defaults read should succeed");
        assert_eq!(
            response,
            serde_json::json!({
@@ -472,7 +484,7 @@ fn test_custom_dictation_secret_save_delete() {

        send_custom(
            conn.cx(),
-            "_goose/dictation/secret/save",
+            "_goose/unstable/dictation/secret/save",
            serde_json::json!({
                "provider": "groq",
                "value": "groq-key",
@@ -481,9 +493,13 @@ fn test_custom_dictation_secret_save_delete() {
        .await
        .expect("dictation secret save should succeed");

-        let config = send_custom(conn.cx(), "_goose/dictation/config", serde_json::json!({}))
-            .await
-            .expect("dictation config should succeed");
+        let config = send_custom(
+            conn.cx(),
+            "_goose/unstable/dictation/config",
+            serde_json::json!({}),
+        )
+        .await
+        .expect("dictation config should succeed");
        assert_eq!(
            config
                .pointer("/providers/groq/configured")
@@ -493,7 +509,7 @@ fn test_custom_dictation_secret_save_delete() {

        let provider_config_result = send_custom(
            conn.cx(),
-            "_goose/dictation/secret/save",
+            "_goose/unstable/dictation/secret/save",
            serde_json::json!({
                "provider": "openai",
                "value": "openai-key",
@@ -507,7 +523,7 @@ fn test_custom_dictation_secret_save_delete() {

        let unknown_result = send_custom(
            conn.cx(),
-            "_goose/dictation/secret/save",
+            "_goose/unstable/dictation/secret/save",
            serde_json::json!({
                "provider": "unknown",
                "value": "key",
@@ -521,7 +537,7 @@ fn test_custom_dictation_secret_save_delete() {

        send_custom(
            conn.cx(),
-            "_goose/dictation/secret/delete",
+            "_goose/unstable/dictation/secret/delete",
            serde_json::json!({
                "provider": "groq",
            }),
@@ -529,9 +545,13 @@ fn test_custom_dictation_secret_save_delete() {
        .await
        .expect("dictation secret delete should succeed");

-        let config = send_custom(conn.cx(), "_goose/dictation/config", serde_json::json!({}))
-            .await
-            .expect("dictation config should succeed");
+        let config = send_custom(
+            conn.cx(),
+            "_goose/unstable/dictation/config",
+            serde_json::json!({}),
+        )
+        .await
+        .expect("dictation config should succeed");
        assert_eq!(
            config
                .pointer("/providers/groq/configured")
@@ -113,7 +113,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {
        write_secrets(&config_dir, "GROQ_API_KEY: fresh-key\n");
        send_custom(
            conn.cx(),
-            "_goose/dictation/secret/save",
+            "_goose/unstable/dictation/secret/save",
            serde_json::json!({
                "provider": "groq",
                "value": "fresh-key",
@@ -133,7 +133,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {
        write_secrets(&config_dir, "{}\n");
        send_custom(
            conn.cx(),
-            "_goose/dictation/secret/delete",
+            "_goose/unstable/dictation/secret/delete",
            serde_json::json!({
                "provider": "groq",
            }),
@@ -151,7 +151,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {

        let save_provider_config = send_custom(
            conn.cx(),
-            "_goose/providers/config/save",
+            "_goose/unstable/providers/config/save",
            serde_json::json!({
                "providerId": "xai",
                "fields": [
@@ -199,7 +199,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {

        let read_provider_config = send_custom(
            conn.cx(),
-            "_goose/providers/config/read",
+            "_goose/unstable/providers/config/read",
            serde_json::json!({
                "providerId": "xai",
            }),
@@ -223,7 +223,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {

        let delete_provider_config = send_custom(
            conn.cx(),
-            "_goose/providers/config/delete",
+            "_goose/unstable/providers/config/delete",
            serde_json::json!({
                "providerId": "xai",
            }),
@@ -255,7 +255,7 @@ fn acp_secret_mutations_and_inventory_refresh_invalidate_global_secret_cache() {

        let refresh = send_custom(
            conn.cx(),
-            "_goose/providers/inventory/refresh",
+            "_goose/unstable/providers/inventory/refresh",
            serde_json::json!({
                "providerIds": ["anthropic"],
            }),