From 20cca8f526a23f1864703660ac1aa0611d84919d Mon Sep 17 00:00:00 2001
From: Dominic Cooney <dominic.cooney@gmail.com>
Date: Mon, 13 Apr 2026 20:42:09 +0900
Subject: [PATCH] Step 1: Foundation & Cutover - SDK adapter layer

- Add @clinebot/core, @clinebot/llms, @clinebot/shared, @clinebot/agents
  as dependencies via file: protocol (linked to ../sdk-wip)
- Create src/sdk/ directory with SdkController stub and barrel export
- Replace src/core/controller/index.ts with re-export from SDK adapter
  (classic Controller accessible via origin/main)
- Extract getStateToPostToWebview() to standalone function for reuse
- Add vitest.config.sdk.ts for SDK adapter tests
- Fix implicit any types in handler modules
- Extension compiles and builds successfully (tsc + esbuild pass)
- Single entry point: no CLINE_SDK flag, SDK adapter is the only codepath

Replaces classic src/core/controller/index.ts (see origin/main)
---
 package-lock.json                             |  119 ++
 package.json                                  |    4 +
 sdk-migration/PROBLEMS.md                     |   25 +-
 .../account/getOrganizationCredits.ts         |    2 +-
 .../account/getUserOrganizations.ts           |    2 +-
 .../controller/file/openFocusChainFile.ts     |    2 +-
 src/core/controller/index.ts                  | 1053 +----------------
 .../state/getStateToPostToWebview.ts          |  197 +++
 src/sdk/SdkController.ts                      |  240 ++++
 src/sdk/index.ts                              |    8 +
 vitest.config.sdk.ts                          |   20 +
 11 files changed, 621 insertions(+), 1051 deletions(-)
 create mode 100644 src/core/controller/state/getStateToPostToWebview.ts
 create mode 100644 src/sdk/SdkController.ts
 create mode 100644 src/sdk/index.ts
 create mode 100644 vitest.config.sdk.ts

diff --git a/package-lock.json b/package-lock.json
index 18b7ef7ff4..598375f34f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -20,6 +20,10 @@
 				"@azure/identity": "^4.13.0",
 				"@bufbuild/protobuf": "^2.2.5",
 				"@cerebras/cerebras_cloud_sdk": "^1.35.0",
+				"@clinebot/agents": "file:../sdk-wip/packages/agents",
+				"@clinebot/core": "file:../sdk-wip/packages/core",
+				"@clinebot/llms": "file:../sdk-wip/packages/llms",
+				"@clinebot/shared": "file:../sdk-wip/packages/shared",
 				"@google-cloud/vertexai": "^1.9.3",
 				"@google/genai": "^1.30.0",
 				"@grpc/grpc-js": "^1.9.15",
@@ -160,6 +164,105 @@
 				"vscode": "^1.84.0"
 			}
 		},
+		"../sdk-wip/packages/agents": {
+			"name": "@clinebot/agents",
+			"version": "0.0.28",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@clinebot/llms": "workspace:*",
+				"zod": "^4.3.6"
+			},
+			"devDependencies": {
+				"@clinebot/shared": "workspace:*"
+			},
+			"engines": {
+				"node": ">=20"
+			}
+		},
+		"../sdk-wip/packages/core": {
+			"name": "@clinebot/core",
+			"version": "0.0.28",
+			"dependencies": {
+				"@clinebot/agents": "workspace:*",
+				"@clinebot/llms": "workspace:*",
+				"@opentelemetry/api": "^1.9.0",
+				"@opentelemetry/api-logs": "^0.214.0",
+				"@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+				"@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
+				"@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+				"@opentelemetry/resources": "^2.6.1",
+				"@opentelemetry/sdk-logs": "^0.214.0",
+				"@opentelemetry/sdk-metrics": "^2.6.1",
+				"@opentelemetry/sdk-trace-base": "^2.6.1",
+				"@opentelemetry/sdk-trace-node": "^2.6.1",
+				"@opentelemetry/semantic-conventions": "^1.40.0",
+				"jiti": "^1.21.7",
+				"nanoid": "^5.1.7",
+				"node-machine-id": "^1.1.12",
+				"simple-git": "^3.32.3",
+				"yaml": "^2.8.2",
+				"zod": "^4.3.6"
+			},
+			"devDependencies": {
+				"@clinebot/rpc": "workspace:*",
+				"@clinebot/shared": "workspace:*"
+			},
+			"engines": {
+				"node": ">=20"
+			}
+		},
+		"../sdk-wip/packages/llms": {
+			"name": "@clinebot/llms",
+			"version": "0.0.28",
+			"dependencies": {
+				"@ai-sdk/amazon-bedrock": "^4.0.89",
+				"@ai-sdk/anthropic": "^3.0.68",
+				"@ai-sdk/google": "^3.0.60",
+				"@ai-sdk/google-vertex": "^4.0.100",
+				"@ai-sdk/mistral": "^3.0.28",
+				"@ai-sdk/openai": "^3.0.52",
+				"@ai-sdk/openai-compatible": "^2.0.38",
+				"@aws-sdk/credential-providers": "^3.922.0",
+				"@clinebot/shared": "workspace:*",
+				"@langfuse/otel": "^4.0.0",
+				"@opentelemetry/api": "^1.9.0",
+				"@opentelemetry/sdk-trace-node": "^2.6.1",
+				"@streamparser/json": "^0.0.21",
+				"ai": "^6.0.144",
+				"ai-sdk-provider-claude-code": "^3.4.3",
+				"ai-sdk-provider-codex-cli": "^1.1.0",
+				"ai-sdk-provider-opencode-sdk": "^3.0.1",
+				"dify-ai-provider": "^1.1.0",
+				"nanoid": "^5.1.7",
+				"zod": "^4.3.6"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"peerDependencies": {
+				"@aws-sdk/client-bedrock-runtime": "^3.0.0"
+			},
+			"peerDependenciesMeta": {
+				"@aws-sdk/client-bedrock-runtime": {
+					"optional": true
+				}
+			}
+		},
+		"../sdk-wip/packages/shared": {
+			"name": "@clinebot/shared",
+			"version": "0.0.28",
+			"dependencies": {
+				"jsonrepair": "^3.13.2",
+				"zod": "^4.3.6",
+				"zod-to-json-schema": "^3.25.1"
+			},
+			"engines": {
+				"node": ">=20"
+			},
+			"optionalDependencies": {
+				"better-sqlite3": "^12.8.0"
+			}
+		},
 		"cli": {
 			"name": "cline",
 			"version": "2.15.0",
@@ -2184,6 +2287,22 @@
 			"integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
 			"license": "MIT"
 		},
+		"node_modules/@clinebot/agents": {
+			"resolved": "../sdk-wip/packages/agents",
+			"link": true
+		},
+		"node_modules/@clinebot/core": {
+			"resolved": "../sdk-wip/packages/core",
+			"link": true
+		},
+		"node_modules/@clinebot/llms": {
+			"resolved": "../sdk-wip/packages/llms",
+			"link": true
+		},
+		"node_modules/@clinebot/shared": {
+			"resolved": "../sdk-wip/packages/shared",
+			"link": true
+		},
 		"node_modules/@colors/colors": {
 			"version": "1.6.0",
 			"resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.6.0.tgz",
diff --git a/package.json b/package.json
index ab083a4d51..35ecd96888 100644
--- a/package.json
+++ b/package.json
@@ -506,6 +506,10 @@
 		"typescript": "^5.4.5"
 	},
 	"dependencies": {
+		"@clinebot/core": "file:../sdk-wip/packages/core",
+		"@clinebot/llms": "file:../sdk-wip/packages/llms",
+		"@clinebot/shared": "file:../sdk-wip/packages/shared",
+		"@clinebot/agents": "file:../sdk-wip/packages/agents",
 		"@anthropic-ai/sdk": "^0.37.0",
 		"@anthropic-ai/vertex-sdk": "^0.6.4",
 		"@aws-sdk/client-bedrock-runtime": "^3.922.0",
diff --git a/sdk-migration/PROBLEMS.md b/sdk-migration/PROBLEMS.md
index 99380828a9..b09c39d470 100644
--- a/sdk-migration/PROBLEMS.md
+++ b/sdk-migration/PROBLEMS.md
@@ -65,7 +65,30 @@ underlying patterns that caused them are relevant.
 
 ## New Issues
 
-*Add issues found during this attempt below this line.*
+### Step 1: Foundation & Cutover — Completed
+
+- **Status**: 🟢 Verified Fixed
+- **Description**: SDK adapter layer created as single entry point. Extension compiles and builds.
+- **Verification**: `npx tsc --noEmit` returns 0 errors. `node esbuild.mjs` produces `dist/extension.js`.
+- **Evidence**: Commit `3dec59fe9` on `sdk-migration-v3` branch.
+
+### S1-1: SdkController stubs log warnings at runtime
+- **Status**: 🟡 Minor
+- **Description**: All unimplemented Controller methods log `[SdkController] STUB: <name> not yet implemented`. This is expected — functionality is added in Steps 4-8.
+- **Root cause**: By design — stub pattern for incremental migration.
+- **Fix**: Implement each method in its corresponding step.
+
+### S1-2: Services not initialized (mcpHub, authService, etc.)
+- **Status**: 🟡 Minor
+- **Description**: The SdkController sets `mcpHub`, `accountService`, `authService`, `ocaAuthService` to `undefined`. Handler modules that access these will throw "not available" errors at runtime.
+- **Root cause**: Services will be properly initialized in Steps 6-7.
+- **Fix**: Wire up services as part of their respective migration steps.
+
+### S1-3: Extension loads but sidebar shows errors
+- **Status**: 🟢 Verified Fixed
+- **Description**: Extension loads, sidebar renders correctly with full UI (chat input, model selector, announcements, auto-approve settings). No error elements in the webview.
+- **Verification**: Debug harness launched with `--auto-launch`, sidebar opened, `document.querySelectorAll("[data-testid=error], .error, .codicon-error").length` returns 0. Sending a message via `ui.send_message` returns `{"sent": true, "method": "newTask"}` without crash. Task doesn't start (expected — `initTask` is a stub).
+- **Evidence**: Debug harness session on 2026-04-13, commit `3dec59fe9`.
 
 <!-- Template:
 ### [ID] Title
diff --git a/src/core/controller/account/getOrganizationCredits.ts b/src/core/controller/account/getOrganizationCredits.ts
index 4e33288388..0554a8680a 100644
--- a/src/core/controller/account/getOrganizationCredits.ts
+++ b/src/core/controller/account/getOrganizationCredits.ts
@@ -32,7 +32,7 @@ export async function getOrganizationCredits(
 			balance: balanceData ? { currentBalance: balanceData.balance / 100 } : { currentBalance: 0 },
 			organizationId: balanceData?.organizationId || "",
 			usageTransactions:
-				usageTransactions?.map((tx) =>
+				usageTransactions?.map((tx: any) =>
 					OrganizationUsageTransaction.create({
 						aiInferenceProviderName: tx.aiInferenceProviderName,
 						aiModelName: tx.aiModelName,
diff --git a/src/core/controller/account/getUserOrganizations.ts b/src/core/controller/account/getUserOrganizations.ts
index c721a07699..d15954992f 100644
--- a/src/core/controller/account/getUserOrganizations.ts
+++ b/src/core/controller/account/getUserOrganizations.ts
@@ -19,7 +19,7 @@ export async function getUserOrganizations(controller: Controller, _request: Emp
 
 		return UserOrganizationsResponse.create({
 			organizations:
-				organizations?.map((org) =>
+				organizations?.map((org: any) =>
 					UserOrganization.create({
 						active: org.active,
 						memberId: org.memberId,
diff --git a/src/core/controller/file/openFocusChainFile.ts b/src/core/controller/file/openFocusChainFile.ts
index 198a8588d4..0523de1a11 100644
--- a/src/core/controller/file/openFocusChainFile.ts
+++ b/src/core/controller/file/openFocusChainFile.ts
@@ -25,7 +25,7 @@ export async function openFocusChainFile(controller: Controller, request: String
 		const lastProgressMessage = clineMessages
 			.slice()
 			.reverse()
-			.find((m) => m.say === "task_progress")
+			.find((m: any) => m.say === "task_progress")
 
 		if (lastProgressMessage && lastProgressMessage.text) {
 			initialFocusChainContent = extractFocusChainListFromText(lastProgressMessage.text) || undefined
diff --git a/src/core/controller/index.ts b/src/core/controller/index.ts
index dbc138d93d..11f3843432 100644
--- a/src/core/controller/index.ts
+++ b/src/core/controller/index.ts
@@ -1,1048 +1,7 @@
-import type { Anthropic } from "@anthropic-ai/sdk"
-import { buildApiHandler } from "@core/api"
-import { getHooksEnabledSafe } from "@core/hooks/hooks-utils"
-import { tryAcquireTaskLockWithRetry } from "@core/task/TaskLockUtils"
-import { detectWorkspaceRoots } from "@core/workspace/detection"
-import { setupWorkspaceManager } from "@core/workspace/setup"
-import type { WorkspaceRootManager } from "@core/workspace/WorkspaceRootManager"
-import { cleanupLegacyCheckpoints } from "@integrations/checkpoints/CheckpointMigration"
-import { ClineAccountService } from "@services/account/ClineAccountService"
-import { McpHub } from "@services/mcp/McpHub"
-import type { ApiProvider, ModelInfo } from "@shared/api"
-import type { ChatContent } from "@shared/ChatContent"
-import type { ExtensionState, Platform } from "@shared/ExtensionMessage"
-import type { HistoryItem } from "@shared/HistoryItem"
-import type { McpMarketplaceCatalog, McpMarketplaceItem } from "@shared/mcp"
-import { type Settings } from "@shared/storage/state-keys"
-import type { Mode } from "@shared/storage/types"
-import type { TelemetrySetting } from "@shared/TelemetrySetting"
-import type { UserInfo } from "@shared/UserInfo"
-import { fileExistsAtPath } from "@utils/fs"
-import axios from "axios"
-import fs from "fs/promises"
-import open from "open"
-import pWaitFor from "p-wait-for"
-import * as path from "path"
-import { ClineEnv } from "@/config"
-import type { FolderLockWithRetryResult } from "@/core/locks/types"
-import { HostProvider } from "@/hosts/host-provider"
-import { ExtensionRegistryInfo } from "@/registry"
-import { AuthService } from "@/services/auth/AuthService"
-import { OcaAuthService } from "@/services/auth/oca/OcaAuthService"
-import { LogoutReason } from "@/services/auth/types"
-import { BannerService } from "@/services/banner/BannerService"
-import { featureFlagsService } from "@/services/feature-flags"
-import { getDistinctId } from "@/services/logging/distinctId"
-import { telemetryService } from "@/services/telemetry"
-import { ClineExtensionContext } from "@/shared/cline"
-import { getAxiosSettings } from "@/shared/net"
-import { ShowMessageType } from "@/shared/proto/host/window"
-import { Logger } from "@/shared/services/Logger"
-import { Session } from "@/shared/services/Session"
-import { getLatestAnnouncementId } from "@/utils/announcements"
-import { getCwd, getDesktopDir } from "@/utils/path"
-import { PromptRegistry } from "../prompts/system-prompt"
-import {
-	ensureCacheDirectoryExists,
-	ensureMcpServersDirectoryExists,
-	ensureSettingsDirectoryExists,
-	GlobalFileNames,
-	writeMcpMarketplaceCatalogToCache,
-} from "../storage/disk"
-import { fetchRemoteConfig } from "../storage/remote-config/fetch"
-import { clearRemoteConfig } from "../storage/remote-config/utils"
-import { type PersistenceErrorEvent, StateManager } from "../storage/StateManager"
-import { Task } from "../task"
-import { sendMcpMarketplaceCatalogEvent } from "./mcp/subscribeToMcpMarketplaceCatalog"
-import { getClineOnboardingModels } from "./models/getClineOnboardingModels"
-import { appendClineStealthModels } from "./models/refreshOpenRouterModels"
-import { checkCliInstallation } from "./state/checkCliInstallation"
-import { sendStateUpdate } from "./state/subscribeToState"
-import { sendChatButtonClickedEvent } from "./ui/subscribeToChatButtonClicked"
+// Replaces classic src/core/controller/index.ts (see origin/main)
+//
+// The Controller class is now provided by the SDK adapter layer.
+// All gRPC handler modules in this directory continue to work as the
+// thunking layer between the webview and the SDK.
 
-/*
-https://github.com/microsoft/vscode-webview-ui-toolkit-samples/blob/main/default/weather-webview/src/providers/WeatherViewProvider.ts
-
-https://github.com/KumarVariable/vscode-extension-sidebar-html/blob/master/src/customSidebarViewProvider.ts
-*/
-
-export class Controller {
-	task?: Task
-
-	mcpHub: McpHub
-	accountService: ClineAccountService
-	authService: AuthService
-	ocaAuthService: OcaAuthService
-	readonly stateManager: StateManager
-
-	// NEW: Add workspace manager (optional initially)
-	private workspaceManager?: WorkspaceRootManager
-	private backgroundCommandRunning = false
-	private backgroundCommandTaskId?: string
-
-	// Flag to prevent duplicate cancellations from spam clicking
-	private cancelInProgress = false
-
-	// Timer for periodic remote config fetching
-	private remoteConfigTimer?: NodeJS.Timeout
-
-	// Public getter for workspace manager with lazy initialization - To get workspaces when task isn't initialized (Used by file mentions)
-	async ensureWorkspaceManager(): Promise<WorkspaceRootManager | undefined> {
-		if (!this.workspaceManager) {
-			try {
-				this.workspaceManager = await setupWorkspaceManager({
-					stateManager: this.stateManager,
-					detectRoots: detectWorkspaceRoots,
-				})
-			} catch (error) {
-				Logger.error("[Controller] Failed to initialize workspace manager:", error)
-			}
-		}
-		return this.workspaceManager
-	}
-
-	// Synchronous getter for workspace manager
-	getWorkspaceManager(): WorkspaceRootManager | undefined {
-		return this.workspaceManager
-	}
-
-	/**
-	 * Starts the periodic remote config fetching timer
-	 * Fetches immediately and then every hour
-	 */
-	private startRemoteConfigTimer() {
-		// Initial fetch
-		fetchRemoteConfig(this)
-		// Set up 1-hour interval
-		this.remoteConfigTimer = setInterval(() => fetchRemoteConfig(this), 3600000) // 1 hour
-	}
-
-	constructor(readonly context: ClineExtensionContext) {
-		Session.reset() // Reset session on controller initialization
-		PromptRegistry.getInstance() // Ensure prompts and tools are registered
-		this.stateManager = StateManager.get()
-		StateManager.get().registerCallbacks({
-			onPersistenceError: async ({ error }: PersistenceErrorEvent) => {
-				// Just log - don't call reInitialize() (that sets isInitialized=false which
-				// breaks running tasks) and don't show a warning (data is safe in memory
-				// and will be retried automatically on the next debounced persistence).
-				Logger.error("[Controller] Storage persistence failed (will retry):", error)
-			},
-			onSyncExternalChange: async () => {
-				await this.postStateToWebview()
-			},
-		})
-		this.authService = AuthService.getInstance(this)
-		this.ocaAuthService = OcaAuthService.initialize(this)
-		this.accountService = ClineAccountService.getInstance()
-		BannerService.initialize(this)
-
-		this.authService.restoreRefreshTokenAndRetrieveAuthInfo().then(() => {
-			this.startRemoteConfigTimer()
-		})
-
-		this.mcpHub = new McpHub(
-			() => ensureMcpServersDirectoryExists(),
-			() => ensureSettingsDirectoryExists(),
-			ExtensionRegistryInfo.version,
-			telemetryService,
-		)
-
-		// Clean up legacy checkpoints
-		cleanupLegacyCheckpoints().catch((error) => {
-			Logger.error("Failed to cleanup legacy checkpoints:", error)
-		})
-
-		// Check CLI installation status once on startup
-		checkCliInstallation(this)
-
-		Logger.log("[Controller] ClineProvider instantiated")
-	}
-
-	/*
-	VSCode extensions use the disposable pattern to clean up resources when the sidebar/editor tab is closed by the user or system. This applies to event listening, commands, interacting with the UI, etc.
-	- https://vscode-docs.readthedocs.io/en/stable/extensions/patterns-and-principles/
-	- https://github.com/microsoft/vscode-extension-samples/blob/main/webview-sample/src/extension.ts
-	*/
-	async dispose() {
-		// Clear the remote config timer
-		if (this.remoteConfigTimer) {
-			clearInterval(this.remoteConfigTimer)
-			this.remoteConfigTimer = undefined
-		}
-
-		await this.clearTask()
-		this.mcpHub.dispose()
-
-		Logger.error("Controller disposed")
-	}
-
-	// Auth methods
-	async handleSignOut() {
-		try {
-			// AuthService now handles its own storage cleanup in handleDeauth()
-			this.stateManager.setGlobalState("userInfo", undefined)
-			clearRemoteConfig()
-
-			// Update API providers through cache service
-			const apiConfiguration = this.stateManager.getApiConfiguration()
-			const updatedConfig = {
-				...apiConfiguration,
-				planModeApiProvider: "openrouter" as ApiProvider,
-				actModeApiProvider: "openrouter" as ApiProvider,
-			}
-			this.stateManager.setApiConfiguration(updatedConfig)
-
-			await this.postStateToWebview()
-			HostProvider.window.showMessage({
-				type: ShowMessageType.INFORMATION,
-				message: "Successfully logged out of Cline",
-			})
-		} catch (_error) {
-			HostProvider.window.showMessage({
-				type: ShowMessageType.INFORMATION,
-				message: "Logout failed",
-			})
-		}
-	}
-
-	// Oca Auth methods
-	async handleOcaSignOut() {
-		try {
-			await this.ocaAuthService.handleDeauth(LogoutReason.USER_INITIATED)
-			await this.postStateToWebview()
-			HostProvider.window.showMessage({
-				type: ShowMessageType.INFORMATION,
-				message: "Successfully logged out of OCA",
-			})
-		} catch (_error) {
-			HostProvider.window.showMessage({
-				type: ShowMessageType.INFORMATION,
-				message: "OCA Logout failed",
-			})
-		}
-	}
-
-	async setUserInfo(info?: UserInfo) {
-		this.stateManager.setGlobalState("userInfo", info)
-	}
-
-	async initTask(
-		task?: string,
-		images?: string[],
-		files?: string[],
-		historyItem?: HistoryItem,
-		taskSettings?: Partial<Settings>,
-	) {
-		// Fire-and-forget: We intentionally don't await fetchRemoteConfig here.
-		// Remote config is already fetched in startRemoteConfigTimer() which runs in the constructor,
-		// so enterprise policies (yoloModeAllowed, allowedMCPServers, etc.) are already applied.
-		// This call just ensures we have the latest state, but we shouldn't block the UI for it.
-		// getGlobalSettingsKey() reads from remoteConfigCache on each call, so any updates
-		// will apply as soon as this fetch completes. The function also calls postStateToWebview()
-		// when done and catches all errors internally.
-		fetchRemoteConfig(this)
-
-		await this.clearTask() // ensures that an existing task doesn't exist before starting a new one, although this shouldn't be possible since user must clear task before starting a new one
-
-		const autoApprovalSettings = this.stateManager.getGlobalSettingsKey("autoApprovalSettings")
-		const shellIntegrationTimeout = this.stateManager.getGlobalSettingsKey("shellIntegrationTimeout")
-		const terminalReuseEnabled = this.stateManager.getGlobalStateKey("terminalReuseEnabled")
-		const vscodeTerminalExecutionMode = this.stateManager.getGlobalStateKey("vscodeTerminalExecutionMode")
-		const terminalOutputLineLimit = this.stateManager.getGlobalSettingsKey("terminalOutputLineLimit")
-		const defaultTerminalProfile = this.stateManager.getGlobalSettingsKey("defaultTerminalProfile")
-		const isNewUser = this.stateManager.getGlobalStateKey("isNewUser")
-		const taskHistory = this.stateManager.getGlobalStateKey("taskHistory")
-
-		const NEW_USER_TASK_COUNT_THRESHOLD = 10
-
-		// Check if the user has completed enough tasks to no longer be considered a "new user"
-		if (isNewUser && !historyItem && taskHistory && taskHistory.length >= NEW_USER_TASK_COUNT_THRESHOLD) {
-			this.stateManager.setGlobalState("isNewUser", false)
-			await this.postStateToWebview()
-		}
-
-		if (autoApprovalSettings) {
-			const updatedAutoApprovalSettings = {
-				...autoApprovalSettings,
-				version: (autoApprovalSettings.version ?? 1) + 1,
-			}
-			this.stateManager.setGlobalState("autoApprovalSettings", updatedAutoApprovalSettings)
-		}
-
-		// Initialize and persist the workspace manager (multi-root or single-root) with telemetry + fallback
-		this.workspaceManager = await setupWorkspaceManager({
-			stateManager: this.stateManager,
-			detectRoots: detectWorkspaceRoots,
-		})
-
-		const cwd = this.workspaceManager?.getPrimaryRoot()?.path || (await getCwd(getDesktopDir()))
-
-		const taskId = historyItem?.id || Date.now().toString()
-
-		// Acquire task lock
-		let taskLockAcquired = false
-		const lockResult: FolderLockWithRetryResult = await tryAcquireTaskLockWithRetry(taskId)
-
-		if (!lockResult.acquired && !lockResult.skipped) {
-			const errorMessage = lockResult.conflictingLock
-				? `Task locked by instance (${lockResult.conflictingLock.held_by})`
-				: "Failed to acquire task lock"
-			throw new Error(errorMessage) // Prevents task initialization
-		}
-
-		taskLockAcquired = lockResult.acquired
-		if (lockResult.acquired) {
-			Logger.debug(`[Task ${taskId}] Task lock acquired`)
-		} else {
-			Logger.debug(`[Task ${taskId}] Task lock skipped (VS Code)`)
-		}
-
-		await this.stateManager.loadTaskSettings(taskId)
-		if (taskSettings) {
-			this.stateManager.setTaskSettingsBatch(taskId, taskSettings)
-		}
-
-		this.task = new Task({
-			controller: this,
-			mcpHub: this.mcpHub,
-			updateTaskHistory: (historyItem) => this.updateTaskHistory(historyItem),
-			postStateToWebview: () => this.postStateToWebview(),
-			reinitExistingTaskFromId: (taskId) => this.reinitExistingTaskFromId(taskId),
-			cancelTask: () => this.cancelTask(),
-			shellIntegrationTimeout,
-			terminalReuseEnabled: terminalReuseEnabled ?? true,
-			terminalOutputLineLimit: terminalOutputLineLimit ?? 500,
-			defaultTerminalProfile: defaultTerminalProfile ?? "default",
-			vscodeTerminalExecutionMode,
-			cwd,
-			stateManager: this.stateManager,
-			workspaceManager: this.workspaceManager,
-			task,
-			images,
-			files,
-			historyItem,
-			taskId,
-			taskLockAcquired,
-		})
-
-		if (historyItem) {
-			this.task.resumeTaskFromHistory()
-		} else if (task || images || files) {
-			this.task.startTask(task, images, files)
-		}
-
-		return this.task.taskId
-	}
-
-	async reinitExistingTaskFromId(taskId: string) {
-		const history = await this.getTaskWithId(taskId)
-		if (history) {
-			await this.initTask(undefined, undefined, undefined, history.historyItem)
-		}
-	}
-
-	async updateTelemetrySetting(telemetrySetting: TelemetrySetting) {
-		// Get previous setting to detect state changes
-		const previousSetting = this.stateManager.getGlobalSettingsKey("telemetrySetting")
-		const wasOptedIn = previousSetting !== "disabled"
-		const isOptedIn = telemetrySetting !== "disabled"
-
-		// Capture opt-out event BEFORE updating (so it gets sent while telemetry is still enabled)
-		if (wasOptedIn && !isOptedIn) {
-			telemetryService.captureUserOptOut()
-		}
-
-		this.stateManager.setGlobalState("telemetrySetting", telemetrySetting)
-		telemetryService.updateTelemetryState(isOptedIn)
-
-		// Capture opt-in event AFTER updating (so telemetry is enabled to receive it)
-		if (!wasOptedIn && isOptedIn) {
-			telemetryService.captureUserOptIn()
-		}
-
-		await this.postStateToWebview()
-	}
-
-	async toggleActModeForYoloMode(): Promise<boolean> {
-		const modeToSwitchTo: Mode = "act"
-
-		// Switch to act mode
-		this.stateManager.setGlobalState("mode", modeToSwitchTo)
-
-		// Update API handler with new mode (buildApiHandler now selects provider based on mode)
-		if (this.task) {
-			const apiConfiguration = this.stateManager.getApiConfiguration()
-			this.task.api = buildApiHandler({ ...apiConfiguration, ulid: this.task.ulid }, modeToSwitchTo)
-		}
-
-		await this.postStateToWebview()
-
-		// Additional safety
-		if (this.task) {
-			return true
-		}
-		return false
-	}
-
-	async togglePlanActMode(modeToSwitchTo: Mode, chatContent?: ChatContent): Promise<boolean> {
-		const didSwitchToActMode = modeToSwitchTo === "act"
-
-		// Store mode to global state
-		this.stateManager.setGlobalState("mode", modeToSwitchTo)
-
-		// Capture mode switch telemetry | Capture regardless of if we know the taskId
-		telemetryService.captureModeSwitch(this.task?.ulid ?? "0", modeToSwitchTo)
-
-		// Update API handler with new mode (buildApiHandler now selects provider based on mode)
-		if (this.task) {
-			const apiConfiguration = this.stateManager.getApiConfiguration()
-			this.task.api = buildApiHandler({ ...apiConfiguration, ulid: this.task.ulid }, modeToSwitchTo)
-		}
-
-		await this.postStateToWebview()
-
-		if (this.task) {
-			if (this.task.taskState.isAwaitingPlanResponse && didSwitchToActMode) {
-				this.task.taskState.didRespondToPlanAskBySwitchingMode = true
-				// Use chatContent if provided, otherwise use default message
-				await this.task.handleWebviewAskResponse(
-					"messageResponse",
-					chatContent?.message || "PLAN_MODE_TOGGLE_RESPONSE",
-					chatContent?.images || [],
-					chatContent?.files || [],
-				)
-
-				return true
-			}
-			this.cancelTask()
-			return false
-		}
-
-		return false
-	}
-
-	async cancelTask() {
-		// Prevent duplicate cancellations from spam clicking
-		if (this.cancelInProgress) {
-			Logger.log(`[Controller.cancelTask] Cancellation already in progress, ignoring duplicate request`)
-			return
-		}
-
-		if (!this.task) {
-			return
-		}
-
-		// Set flag to prevent concurrent cancellations
-		this.cancelInProgress = true
-
-		try {
-			this.updateBackgroundCommandState(false)
-
-			try {
-				await this.task.abortTask()
-			} catch (error) {
-				Logger.error("Failed to abort task", error)
-			}
-
-			await pWaitFor(
-				() =>
-					this.task === undefined ||
-					this.task.taskState.isStreaming === false ||
-					this.task.taskState.didFinishAbortingStream ||
-					this.task.taskState.isWaitingForFirstChunk, // if only first chunk is processed, then there's no need to wait for graceful abort (closes edits, browser, etc)
-				{
-					timeout: 3_000,
-				},
-			).catch(() => {
-				Logger.error("Failed to abort task")
-			})
-
-			if (this.task) {
-				// 'abandoned' will prevent this cline instance from affecting future cline instance gui. this may happen if its hanging on a streaming request
-				this.task.taskState.abandoned = true
-			}
-
-			// Small delay to ensure state manager has persisted the history update
-			//await new Promise((resolve) => setTimeout(resolve, 100))
-
-			// NOW try to get history after abort has finished (hook may have saved messages)
-			let historyItem: HistoryItem | undefined
-			try {
-				const result = await this.getTaskWithId(this.task.taskId)
-				historyItem = result.historyItem
-			} catch (error) {
-				// Task not in history yet (new task with no messages); catch the
-				// error to enable the agent to continue making progress.
-				Logger.log(`[Controller.cancelTask] Task not found in history: ${error}`)
-			}
-
-			// Only re-initialize if we found a history item, otherwise just clear
-			if (historyItem) {
-				// Re-initialize task to keep it visible in UI with resume button
-				await this.initTask(undefined, undefined, undefined, historyItem, undefined)
-			} else {
-				await this.clearTask()
-			}
-
-			await this.postStateToWebview()
-		} finally {
-			// Always clear the flag, even if cancellation fails
-			this.cancelInProgress = false
-		}
-	}
-
-	updateBackgroundCommandState(running: boolean, taskId?: string) {
-		const nextTaskId = running ? taskId : undefined
-		if (this.backgroundCommandRunning === running && this.backgroundCommandTaskId === nextTaskId) {
-			return
-		}
-		this.backgroundCommandRunning = running
-		this.backgroundCommandTaskId = nextTaskId
-		void this.postStateToWebview()
-	}
-
-	async cancelBackgroundCommand(): Promise<void> {
-		const didCancel = await this.task?.cancelBackgroundCommand()
-		if (!didCancel) {
-			this.updateBackgroundCommandState(false)
-		}
-	}
-
-	async handleAuthCallback(customToken: string, provider: string | null = null) {
-		try {
-			await this.authService.handleAuthCallback(customToken, provider ? provider : "google")
-
-			const clineProvider: ApiProvider = "cline"
-
-			// Get current settings to determine how to update providers
-			const planActSeparateModelsSetting = this.stateManager.getGlobalSettingsKey("planActSeparateModelsSetting")
-
-			const currentMode = this.stateManager.getGlobalSettingsKey("mode")
-
-			// Get current API configuration from cache
-			const currentApiConfiguration = this.stateManager.getApiConfiguration()
-
-			const updatedConfig = { ...currentApiConfiguration }
-
-			if (planActSeparateModelsSetting) {
-				// Only update the current mode's provider
-				if (currentMode === "plan") {
-					updatedConfig.planModeApiProvider = clineProvider
-				} else {
-					updatedConfig.actModeApiProvider = clineProvider
-				}
-			} else {
-				// Update both modes to keep them in sync
-				updatedConfig.planModeApiProvider = clineProvider
-				updatedConfig.actModeApiProvider = clineProvider
-			}
-
-			// Update the API configuration through cache service
-			this.stateManager.setApiConfiguration(updatedConfig)
-
-			// Mark welcome view as completed since user has successfully logged in
-			this.stateManager.setGlobalState("welcomeViewCompleted", true)
-
-			await fetchRemoteConfig(this)
-
-			if (this.task) {
-				this.task.api = buildApiHandler({ ...updatedConfig, ulid: this.task.ulid }, currentMode)
-			}
-
-			await this.postStateToWebview()
-		} catch (error) {
-			Logger.error("Failed to handle auth callback:", error)
-			HostProvider.window.showMessage({
-				type: ShowMessageType.ERROR,
-				message: "Failed to log in to Cline",
-			})
-			// Even on login failure, we preserve any existing tokens
-			// Only clear tokens on explicit logout
-		}
-	}
-
-	async handleOcaAuthCallback(code: string, state: string) {
-		try {
-			await this.ocaAuthService.handleAuthCallback(code, state)
-
-			const ocaProvider: ApiProvider = "oca"
-
-			// Get current settings to determine how to update providers
-			const planActSeparateModelsSetting = this.stateManager.getGlobalSettingsKey("planActSeparateModelsSetting")
-
-			const currentMode = this.stateManager.getGlobalSettingsKey("mode")
-
-			// Get current API configuration from cache
-			const currentApiConfiguration = this.stateManager.getApiConfiguration()
-
-			const updatedConfig = { ...currentApiConfiguration }
-
-			if (planActSeparateModelsSetting) {
-				// Only update the current mode's provider
-				if (currentMode === "plan") {
-					updatedConfig.planModeApiProvider = ocaProvider
-				} else {
-					updatedConfig.actModeApiProvider = ocaProvider
-				}
-			} else {
-				// Update both modes to keep them in sync
-				updatedConfig.planModeApiProvider = ocaProvider
-				updatedConfig.actModeApiProvider = ocaProvider
-			}
-
-			// Update the API configuration through cache service
-			this.stateManager.setApiConfiguration(updatedConfig)
-
-			// Mark welcome view as completed since user has successfully logged in
-			this.stateManager.setGlobalState("welcomeViewCompleted", true)
-
-			if (this.task) {
-				this.task.api = buildApiHandler({ ...updatedConfig, ulid: this.task.ulid }, currentMode)
-			}
-
-			await this.postStateToWebview()
-		} catch (error) {
-			Logger.error("Failed to handle auth callback:", error)
-			HostProvider.window.showMessage({
-				type: ShowMessageType.ERROR,
-				message: "Failed to log in to OCA",
-			})
-			// Even on login failure, we preserve any existing tokens
-			// Only clear tokens on explicit logout
-		}
-	}
-
-	async handleMcpOAuthCallback(serverHash: string, code: string, state: string | null) {
-		try {
-			await this.mcpHub.completeOAuth(serverHash, code, state)
-			await this.postStateToWebview()
-			HostProvider.window.showMessage({
-				type: ShowMessageType.INFORMATION,
-				message: `Successfully authenticated MCP server`,
-			})
-		} catch (error) {
-			Logger.error("Failed to complete MCP OAuth:", error)
-			HostProvider.window.showMessage({
-				type: ShowMessageType.ERROR,
-				message: `Failed to authenticate MCP server`,
-			})
-		}
-	}
-
-	async handleTaskCreation(prompt: string) {
-		await sendChatButtonClickedEvent()
-		await this.initTask(prompt)
-	}
-
-	// MCP Marketplace
-	private async fetchMcpMarketplaceFromApi(): Promise<McpMarketplaceCatalog> {
-		const response = await axios.get(`${ClineEnv.config().mcpBaseUrl}/marketplace`, {
-			headers: {
-				"Content-Type": "application/json",
-				"User-Agent": "cline-vscode-extension",
-			},
-			...getAxiosSettings(),
-		})
-
-		if (!response.data) {
-			throw new Error("Invalid response from MCP marketplace API")
-		}
-
-		// Get allowlist from remote config
-		const allowedMCPServers = this.stateManager.getRemoteConfigSettings().allowedMCPServers
-
-		let items: McpMarketplaceItem[] = (response.data || []).map((item: McpMarketplaceItem) => ({
-			...item,
-			githubStars: item.githubStars ?? 0,
-			downloadCount: item.downloadCount ?? 0,
-			tags: item.tags ?? [],
-		}))
-
-		// Filter by allowlist if configured
-		if (allowedMCPServers) {
-			const allowedIds = new Set(allowedMCPServers.map((server) => server.id))
-			items = items.filter((item: McpMarketplaceItem) => allowedIds.has(item.mcpId))
-		}
-
-		const catalog: McpMarketplaceCatalog = { items }
-
-		// Store in cache file
-		await writeMcpMarketplaceCatalogToCache(catalog)
-		return catalog
-	}
-
-	async refreshMcpMarketplace(sendCatalogEvent: boolean): Promise<McpMarketplaceCatalog | undefined> {
-		try {
-			const catalog = await this.fetchMcpMarketplaceFromApi()
-			if (catalog && sendCatalogEvent) {
-				await sendMcpMarketplaceCatalogEvent(catalog)
-			}
-			return catalog
-		} catch (error) {
-			Logger.error("Failed to refresh MCP marketplace:", error)
-			return undefined
-		}
-	}
-
-	// OpenRouter
-
-	async handleOpenRouterCallback(code: string) {
-		let apiKey: string
-		try {
-			const response = await axios.post("https://openrouter.ai/api/v1/auth/keys", { code }, getAxiosSettings())
-			if (response.data && response.data.key) {
-				apiKey = response.data.key
-			} else {
-				throw new Error("Invalid response from OpenRouter API")
-			}
-		} catch (error) {
-			Logger.error("Error exchanging code for API key:", error)
-			throw error
-		}
-
-		const openrouter: ApiProvider = "openrouter"
-		const currentMode = this.stateManager.getGlobalSettingsKey("mode")
-
-		// Update API configuration through cache service
-		const currentApiConfiguration = this.stateManager.getApiConfiguration()
-		const updatedConfig = {
-			...currentApiConfiguration,
-			planModeApiProvider: openrouter,
-			actModeApiProvider: openrouter,
-			openRouterApiKey: apiKey,
-		}
-		this.stateManager.setApiConfiguration(updatedConfig)
-
-		await this.postStateToWebview()
-		if (this.task) {
-			this.task.api = buildApiHandler({ ...updatedConfig, ulid: this.task.ulid }, currentMode)
-		}
-		// Dont send settingsButtonClicked because its bad ux if user is on welcome
-	}
-
-	// Requesty
-
-	async handleRequestyCallback(code: string) {
-		const requesty: ApiProvider = "requesty"
-		const currentMode = this.stateManager.getGlobalSettingsKey("mode")
-		const currentApiConfiguration = this.stateManager.getApiConfiguration()
-		const updatedConfig = {
-			...currentApiConfiguration,
-			planModeApiProvider: requesty,
-			actModeApiProvider: requesty,
-			requestyApiKey: code,
-		}
-		this.stateManager.setApiConfiguration(updatedConfig)
-		await this.postStateToWebview()
-		if (this.task) {
-			this.task.api = buildApiHandler({ ...updatedConfig, ulid: this.task.ulid }, currentMode)
-		}
-	}
-
-	// Read OpenRouter models from disk cache
-	async readOpenRouterModels(): Promise<Record<string, ModelInfo> | undefined> {
-		const openRouterModelsFilePath = path.join(await ensureCacheDirectoryExists(), GlobalFileNames.openRouterModels)
-		try {
-			if (await fileExistsAtPath(openRouterModelsFilePath)) {
-				const fileContents = await fs.readFile(openRouterModelsFilePath, "utf8")
-				const models = JSON.parse(fileContents)
-				// Append stealth models
-				return appendClineStealthModels(models)
-			}
-		} catch (error) {
-			Logger.error("Error reading cached OpenRouter models:", error)
-		}
-		return undefined
-	}
-
-	// Hicap
-	async handleHicapCallback(code: string) {
-		const apiKey: string = code
-
-		const hicap: ApiProvider = "hicap"
-		const currentMode = this.stateManager.getGlobalSettingsKey("mode")
-
-		// Update API configuration through cache service
-		const currentApiConfiguration = this.stateManager.getApiConfiguration()
-		const updatedConfig = {
-			...currentApiConfiguration,
-			planModeApiProvider: hicap,
-			actModeApiProvider: hicap,
-			hicapApiKey: apiKey,
-		}
-		this.stateManager.setApiConfiguration(updatedConfig)
-
-		await this.postStateToWebview()
-		this.accountService
-		if (this.task) {
-			this.task.api = buildApiHandler({ ...updatedConfig, ulid: this.task.ulid }, currentMode)
-		}
-	}
-
-	// Task history
-
-	async getTaskWithId(id: string): Promise<{
-		historyItem: HistoryItem
-		taskDirPath: string
-		apiConversationHistoryFilePath: string
-		uiMessagesFilePath: string
-		contextHistoryFilePath: string
-		taskMetadataFilePath: string
-		apiConversationHistory: Anthropic.MessageParam[]
-	}> {
-		const history = this.stateManager.getGlobalStateKey("taskHistory")
-		const historyItem = history.find((item) => item.id === id)
-		if (historyItem) {
-			const taskDirPath = path.join(HostProvider.get().globalStorageFsPath, "tasks", id)
-			const apiConversationHistoryFilePath = path.join(taskDirPath, GlobalFileNames.apiConversationHistory)
-			const uiMessagesFilePath = path.join(taskDirPath, GlobalFileNames.uiMessages)
-			const contextHistoryFilePath = path.join(taskDirPath, GlobalFileNames.contextHistory)
-			const taskMetadataFilePath = path.join(taskDirPath, GlobalFileNames.taskMetadata)
-			const fileExists = await fileExistsAtPath(apiConversationHistoryFilePath)
-			if (fileExists) {
-				const apiConversationHistory = JSON.parse(await fs.readFile(apiConversationHistoryFilePath, "utf8"))
-				return {
-					historyItem,
-					taskDirPath,
-					apiConversationHistoryFilePath,
-					uiMessagesFilePath,
-					contextHistoryFilePath,
-					taskMetadataFilePath,
-					apiConversationHistory,
-				}
-			}
-		}
-		// if we tried to get a task that doesn't exist, remove it from state
-		// FIXME: this seems to happen sometimes when the json file doesn't save to disk for some reason
-		await this.deleteTaskFromState(id)
-		throw new Error("Task not found")
-	}
-
-	async exportTaskWithId(id: string) {
-		const { taskDirPath } = await this.getTaskWithId(id)
-		Logger.log(`[EXPORT] Opening task directory: ${taskDirPath}`)
-		await open(taskDirPath)
-	}
-
-	async deleteTaskFromState(id: string) {
-		// Remove the task from history
-		const taskHistory = this.stateManager.getGlobalStateKey("taskHistory")
-		const updatedTaskHistory = taskHistory.filter((task) => task.id !== id)
-		this.stateManager.setGlobalState("taskHistory", updatedTaskHistory)
-
-		// Notify the webview that the task has been deleted
-		await this.postStateToWebview()
-
-		return updatedTaskHistory
-	}
-
-	async postStateToWebview() {
-		const state = await this.getStateToPostToWebview()
-		await sendStateUpdate(state)
-	}
-
-	async getStateToPostToWebview(): Promise<ExtensionState> {
-		// Get API configuration from cache for immediate access
-		const onboardingModels = getClineOnboardingModels()
-		const apiConfiguration = this.stateManager.getApiConfiguration()
-		const lastShownAnnouncementId = this.stateManager.getGlobalStateKey("lastShownAnnouncementId")
-		const taskHistory = this.stateManager.getGlobalStateKey("taskHistory")
-		const autoApprovalSettings = this.stateManager.getGlobalSettingsKey("autoApprovalSettings")
-		const browserSettings = this.stateManager.getGlobalSettingsKey("browserSettings")
-		const focusChainSettings = this.stateManager.getGlobalSettingsKey("focusChainSettings")
-		const preferredLanguage = this.stateManager.getGlobalSettingsKey("preferredLanguage")
-		const mode = this.stateManager.getGlobalSettingsKey("mode")
-		const strictPlanModeEnabled = this.stateManager.getGlobalSettingsKey("strictPlanModeEnabled")
-		const yoloModeToggled = this.stateManager.getGlobalSettingsKey("yoloModeToggled")
-		const useAutoCondense = this.stateManager.getGlobalSettingsKey("useAutoCondense")
-		const subagentsEnabled = this.stateManager.getGlobalSettingsKey("subagentsEnabled")
-		const userInfo = this.stateManager.getGlobalStateKey("userInfo")
-		const mcpMarketplaceEnabled = this.stateManager.getGlobalStateKey("mcpMarketplaceEnabled")
-		const mcpDisplayMode = this.stateManager.getGlobalStateKey("mcpDisplayMode")
-		const telemetrySetting = this.stateManager.getGlobalSettingsKey("telemetrySetting")
-		const planActSeparateModelsSetting = this.stateManager.getGlobalSettingsKey("planActSeparateModelsSetting")
-		const enableCheckpointsSetting = this.stateManager.getGlobalSettingsKey("enableCheckpointsSetting")
-		const globalClineRulesToggles = this.stateManager.getGlobalSettingsKey("globalClineRulesToggles")
-		const globalWorkflowToggles = this.stateManager.getGlobalSettingsKey("globalWorkflowToggles")
-		const globalSkillsToggles = this.stateManager.getGlobalSettingsKey("globalSkillsToggles")
-		const localSkillsToggles = this.stateManager.getWorkspaceStateKey("localSkillsToggles")
-		const remoteRulesToggles = this.stateManager.getGlobalStateKey("remoteRulesToggles")
-		const remoteWorkflowToggles = this.stateManager.getGlobalStateKey("remoteWorkflowToggles")
-		const shellIntegrationTimeout = this.stateManager.getGlobalSettingsKey("shellIntegrationTimeout")
-		const terminalReuseEnabled = this.stateManager.getGlobalStateKey("terminalReuseEnabled")
-		const vscodeTerminalExecutionMode = this.stateManager.getGlobalStateKey("vscodeTerminalExecutionMode")
-		const defaultTerminalProfile = this.stateManager.getGlobalSettingsKey("defaultTerminalProfile")
-		const isNewUser = this.stateManager.getGlobalStateKey("isNewUser")
-		// Can be undefined but is set to either true or false by the migration that runs on extension launch in extension.ts
-		const welcomeViewCompleted = !!this.stateManager.getGlobalStateKey("welcomeViewCompleted")
-
-		const customPrompt = this.stateManager.getGlobalSettingsKey("customPrompt")
-		const mcpResponsesCollapsed = this.stateManager.getGlobalStateKey("mcpResponsesCollapsed")
-		const terminalOutputLineLimit = this.stateManager.getGlobalSettingsKey("terminalOutputLineLimit")
-		const maxConsecutiveMistakes = this.stateManager.getGlobalSettingsKey("maxConsecutiveMistakes")
-		const favoritedModelIds = this.stateManager.getGlobalStateKey("favoritedModelIds")
-		const lastDismissedInfoBannerVersion = this.stateManager.getGlobalStateKey("lastDismissedInfoBannerVersion") || 0
-		const lastDismissedModelBannerVersion = this.stateManager.getGlobalStateKey("lastDismissedModelBannerVersion") || 0
-		const lastDismissedCliBannerVersion = this.stateManager.getGlobalStateKey("lastDismissedCliBannerVersion") || 0
-		const dismissedBanners = this.stateManager.getGlobalStateKey("dismissedBanners")
-		const doubleCheckCompletionEnabled = this.stateManager.getGlobalSettingsKey("doubleCheckCompletionEnabled")
-		const lazyTeammateModeEnabled = this.stateManager.getGlobalSettingsKey("lazyTeammateModeEnabled")
-		const showFeatureTips = this.stateManager.getGlobalSettingsKey("showFeatureTips")
-
-		const localClineRulesToggles = this.stateManager.getWorkspaceStateKey("localClineRulesToggles")
-		const localWindsurfRulesToggles = this.stateManager.getWorkspaceStateKey("localWindsurfRulesToggles")
-		const localCursorRulesToggles = this.stateManager.getWorkspaceStateKey("localCursorRulesToggles")
-		const localAgentsRulesToggles = this.stateManager.getWorkspaceStateKey("localAgentsRulesToggles")
-		const workflowToggles = this.stateManager.getWorkspaceStateKey("workflowToggles")
-
-		const currentTaskItem = this.task?.taskId ? (taskHistory || []).find((item) => item.id === this.task?.taskId) : undefined
-		// Spread to create new array reference - React needs this to detect changes in useEffect dependencies
-		const clineMessages = [...(this.task?.messageStateHandler.getClineMessages() || [])]
-		const checkpointManagerErrorMessage = this.task?.taskState.checkpointManagerErrorMessage
-
-		const processedTaskHistory = (taskHistory || [])
-			.filter((item) => item.ts && item.task)
-			.sort((a, b) => b.ts - a.ts)
-			.slice(0, 100) // for now we're only getting the latest 100 tasks, but a better solution here is to only pass in 3 for recent task history, and then get the full task history on demand when going to the task history view (maybe with pagination?)
-
-		const latestAnnouncementId = getLatestAnnouncementId()
-		const shouldShowAnnouncement = lastShownAnnouncementId !== latestAnnouncementId
-		const platform = process.platform as Platform
-		const distinctId = getDistinctId()
-		const version = ExtensionRegistryInfo.version
-		const clineConfig = ClineEnv.config()
-		const environment = clineConfig.environment
-		const banners = BannerService.get().getActiveBanners() ?? []
-		const welcomeBanners = BannerService.get().getWelcomeBanners() ?? []
-
-		// Check OpenAI Codex authentication status
-		const { openAiCodexOAuthManager } = await import("@/integrations/openai-codex/oauth")
-		const openAiCodexIsAuthenticated = await openAiCodexOAuthManager.isAuthenticated()
-
-		return {
-			version,
-			apiConfiguration,
-			currentTaskItem,
-			clineMessages,
-			currentFocusChainChecklist: this.task?.taskState.currentFocusChainChecklist || null,
-			checkpointManagerErrorMessage,
-			autoApprovalSettings,
-			browserSettings,
-			focusChainSettings,
-			preferredLanguage,
-			mode,
-			strictPlanModeEnabled,
-			yoloModeToggled,
-			useAutoCondense,
-			subagentsEnabled,
-			userInfo,
-			mcpMarketplaceEnabled,
-			mcpDisplayMode,
-			telemetrySetting,
-			planActSeparateModelsSetting,
-			enableCheckpointsSetting: enableCheckpointsSetting ?? true,
-			platform,
-			environment,
-			distinctId,
-			globalClineRulesToggles: globalClineRulesToggles || {},
-			localClineRulesToggles: localClineRulesToggles || {},
-			localWindsurfRulesToggles: localWindsurfRulesToggles || {},
-			localCursorRulesToggles: localCursorRulesToggles || {},
-			localAgentsRulesToggles: localAgentsRulesToggles || {},
-			localWorkflowToggles: workflowToggles || {},
-			globalWorkflowToggles: globalWorkflowToggles || {},
-			globalSkillsToggles: globalSkillsToggles || {},
-			localSkillsToggles: localSkillsToggles || {},
-			remoteRulesToggles: remoteRulesToggles,
-			remoteWorkflowToggles: remoteWorkflowToggles,
-			shellIntegrationTimeout,
-			terminalReuseEnabled,
-			vscodeTerminalExecutionMode: vscodeTerminalExecutionMode,
-			defaultTerminalProfile,
-			isNewUser,
-			welcomeViewCompleted,
-			onboardingModels,
-			mcpResponsesCollapsed,
-			terminalOutputLineLimit,
-			maxConsecutiveMistakes,
-			customPrompt,
-			taskHistory: processedTaskHistory,
-			shouldShowAnnouncement,
-			favoritedModelIds,
-			backgroundCommandRunning: this.backgroundCommandRunning,
-			backgroundCommandTaskId: this.backgroundCommandTaskId,
-			// NEW: Add workspace information
-			workspaceRoots: this.workspaceManager?.getRoots() ?? [],
-			primaryRootIndex: this.workspaceManager?.getPrimaryIndex() ?? 0,
-			isMultiRootWorkspace: (this.workspaceManager?.getRoots().length ?? 0) > 1,
-			multiRootSetting: {
-				user: this.stateManager.getGlobalStateKey("multiRootEnabled"),
-				featureFlag: true, // Multi-root workspace is now always enabled
-			},
-			clineWebToolsEnabled: {
-				user: this.stateManager.getGlobalSettingsKey("clineWebToolsEnabled"),
-				featureFlag: featureFlagsService.getWebtoolsEnabled(),
-			},
-			worktreesEnabled: {
-				user: this.stateManager.getGlobalSettingsKey("worktreesEnabled"),
-				featureFlag: featureFlagsService.getWorktreesEnabled(),
-			},
-			hooksEnabled: getHooksEnabledSafe(this.stateManager.getGlobalSettingsKey("hooksEnabled")),
-			lastDismissedInfoBannerVersion,
-			lastDismissedModelBannerVersion,
-			remoteConfigSettings: this.stateManager.getRemoteConfigSettings(),
-			lastDismissedCliBannerVersion,
-			dismissedBanners,
-			nativeToolCallSetting: this.stateManager.getGlobalStateKey("nativeToolCallEnabled"),
-			enableParallelToolCalling: this.stateManager.getGlobalSettingsKey("enableParallelToolCalling"),
-			backgroundEditEnabled: this.stateManager.getGlobalSettingsKey("backgroundEditEnabled"),
-			optOutOfRemoteConfig: this.stateManager.getGlobalSettingsKey("optOutOfRemoteConfig"),
-			doubleCheckCompletionEnabled,
-			lazyTeammateModeEnabled,
-			showFeatureTips,
-			banners,
-			welcomeBanners,
-			openAiCodexIsAuthenticated,
-		}
-	}
-
-	async clearTask() {
-		if (this.task) {
-			// Clear task settings cache when task ends
-			await this.stateManager.clearTaskSettings()
-		}
-		await this.task?.abortTask()
-		this.task = undefined // removes reference to it, so once promises end it will be garbage collected
-	}
-
-	// Caching mechanism to keep track of webview messages + API conversation history per provider instance
-
-	/*
-	Now that we use retainContextWhenHidden, we don't have to store a cache of cline messages in the user's state, but we could to reduce memory footprint in long conversations.
-
-	- We have to be careful of what state is shared between ClineProvider instances since there could be multiple instances of the extension running at once. For example when we cached cline messages using the same key, two instances of the extension could end up using the same key and overwriting each other's messages.
-	- Some state does need to be shared between the instances, i.e. the API key--however there doesn't seem to be a good way to notify the other instances that the API key has changed.
-
-	We need to use a unique identifier for each ClineProvider instance's message cache since we could be running several instances of the extension outside of just the sidebar i.e. in editor panels.
-
-	// conversation history to send in API requests
-
-	/*
-	It seems that some API messages do not comply with vscode state requirements. Either the Anthropic library is manipulating these values somehow in the backend in a way that's creating cyclic references, or the API returns a function or a Symbol as part of the message content.
-	VSCode docs about state: "The value must be JSON-stringifyable ... value — A value. MUST not contain cyclic references."
-	For now we'll store the conversation history in memory, and if we need to store in state directly we'd need to do a manual conversion to ensure proper json stringification.
-	*/
-
-	async updateTaskHistory(item: HistoryItem): Promise<HistoryItem[]> {
-		const history = this.stateManager.getGlobalStateKey("taskHistory")
-		const existingItemIndex = history.findIndex((h) => h.id === item.id)
-		if (existingItemIndex !== -1) {
-			history[existingItemIndex] = item
-		} else {
-			history.push(item)
-		}
-		this.stateManager.setGlobalState("taskHistory", history)
-		return history
-	}
-}
+export { Controller } from "@/sdk/SdkController"
diff --git a/src/core/controller/state/getStateToPostToWebview.ts b/src/core/controller/state/getStateToPostToWebview.ts
new file mode 100644
index 0000000000..efa7d23c0d
--- /dev/null
+++ b/src/core/controller/state/getStateToPostToWebview.ts
@@ -0,0 +1,197 @@
+// Extracted from classic src/core/controller/index.ts (see origin/main)
+//
+// Standalone function to build ExtensionState from a Controller instance.
+// This allows the SdkController to reuse the classic state-building logic
+// without inheriting the entire classic Controller implementation.
+
+import { getHooksEnabledSafe } from "@core/hooks/hooks-utils"
+import type { ExtensionState, Platform } from "@shared/ExtensionMessage"
+import { ClineEnv } from "@/config"
+import { ExtensionRegistryInfo } from "@/registry"
+import { BannerService } from "@/services/banner/BannerService"
+import { featureFlagsService } from "@/services/feature-flags"
+import { getDistinctId } from "@/services/logging/distinctId"
+import { getLatestAnnouncementId } from "@/utils/announcements"
+import { getClineOnboardingModels } from "../models/getClineOnboardingModels"
+
+/**
+ * Builds the ExtensionState object to push to the webview.
+ * Extracted from the classic Controller.getStateToPostToWebview().
+ */
+export async function getStateToPostToWebview(controller: {
+	task?: any
+	stateManager: any
+	mcpHub?: any
+	backgroundCommandRunning?: boolean
+	backgroundCommandTaskId?: string
+	workspaceManager?: any
+}): Promise<ExtensionState> {
+	const stateManager = controller.stateManager
+
+	// Get API configuration from cache for immediate access
+	const onboardingModels = getClineOnboardingModels()
+	const apiConfiguration = stateManager.getApiConfiguration()
+	const lastShownAnnouncementId = stateManager.getGlobalStateKey("lastShownAnnouncementId")
+	const taskHistory = stateManager.getGlobalStateKey("taskHistory")
+	const autoApprovalSettings = stateManager.getGlobalSettingsKey("autoApprovalSettings")
+	const browserSettings = stateManager.getGlobalSettingsKey("browserSettings")
+	const focusChainSettings = stateManager.getGlobalSettingsKey("focusChainSettings")
+	const preferredLanguage = stateManager.getGlobalSettingsKey("preferredLanguage")
+	const mode = stateManager.getGlobalSettingsKey("mode")
+	const strictPlanModeEnabled = stateManager.getGlobalSettingsKey("strictPlanModeEnabled")
+	const yoloModeToggled = stateManager.getGlobalSettingsKey("yoloModeToggled")
+	const useAutoCondense = stateManager.getGlobalSettingsKey("useAutoCondense")
+	const subagentsEnabled = stateManager.getGlobalSettingsKey("subagentsEnabled")
+	const userInfo = stateManager.getGlobalStateKey("userInfo")
+	const mcpMarketplaceEnabled = stateManager.getGlobalStateKey("mcpMarketplaceEnabled")
+	const mcpDisplayMode = stateManager.getGlobalStateKey("mcpDisplayMode")
+	const telemetrySetting = stateManager.getGlobalSettingsKey("telemetrySetting")
+	const planActSeparateModelsSetting = stateManager.getGlobalSettingsKey("planActSeparateModelsSetting")
+	const enableCheckpointsSetting = stateManager.getGlobalSettingsKey("enableCheckpointsSetting")
+	const globalClineRulesToggles = stateManager.getGlobalStateKey("globalClineRulesToggles")
+	const globalWorkflowToggles = stateManager.getGlobalStateKey("globalWorkflowToggles")
+	const globalSkillsToggles = stateManager.getGlobalStateKey("globalSkillsToggles")
+	const localSkillsToggles = stateManager.getWorkspaceStateKey("localSkillsToggles")
+	const remoteRulesToggles = stateManager.getGlobalStateKey("remoteRulesToggles")
+	const remoteWorkflowToggles = stateManager.getGlobalStateKey("remoteWorkflowToggles")
+	const shellIntegrationTimeout = stateManager.getGlobalSettingsKey("shellIntegrationTimeout")
+	const terminalReuseEnabled = stateManager.getGlobalStateKey("terminalReuseEnabled")
+	const vscodeTerminalExecutionMode = stateManager.getGlobalStateKey("vscodeTerminalExecutionMode")
+	const defaultTerminalProfile = stateManager.getGlobalSettingsKey("defaultTerminalProfile")
+	const isNewUser = stateManager.getGlobalStateKey("isNewUser")
+	const welcomeViewCompleted = !!stateManager.getGlobalStateKey("welcomeViewCompleted")
+
+	const customPrompt = stateManager.getGlobalSettingsKey("customPrompt")
+	const mcpResponsesCollapsed = stateManager.getGlobalStateKey("mcpResponsesCollapsed")
+	const terminalOutputLineLimit = stateManager.getGlobalSettingsKey("terminalOutputLineLimit")
+	const maxConsecutiveMistakes = stateManager.getGlobalSettingsKey("maxConsecutiveMistakes")
+	const favoritedModelIds = stateManager.getGlobalStateKey("favoritedModelIds")
+	const lastDismissedInfoBannerVersion = stateManager.getGlobalStateKey("lastDismissedInfoBannerVersion") || 0
+	const lastDismissedModelBannerVersion = stateManager.getGlobalStateKey("lastDismissedModelBannerVersion") || 0
+	const lastDismissedCliBannerVersion = stateManager.getGlobalStateKey("lastDismissedCliBannerVersion") || 0
+	const dismissedBanners = stateManager.getGlobalStateKey("dismissedBanners")
+	const doubleCheckCompletionEnabled = stateManager.getGlobalSettingsKey("doubleCheckCompletionEnabled")
+	const lazyTeammateModeEnabled = stateManager.getGlobalSettingsKey("lazyTeammateModeEnabled")
+	const showFeatureTips = stateManager.getGlobalSettingsKey("showFeatureTips")
+
+	const localClineRulesToggles = stateManager.getWorkspaceStateKey("localClineRulesToggles")
+	const localWindsurfRulesToggles = stateManager.getWorkspaceStateKey("localWindsurfRulesToggles")
+	const localCursorRulesToggles = stateManager.getWorkspaceStateKey("localCursorRulesToggles")
+	const localAgentsRulesToggles = stateManager.getWorkspaceStateKey("localAgentsRulesToggles")
+	const workflowToggles = stateManager.getWorkspaceStateKey("workflowToggles")
+
+	const currentTaskItem = controller.task?.taskId
+		? (taskHistory || []).find((item: any) => item.id === controller.task?.taskId)
+		: undefined
+	const clineMessages = [...(controller.task?.messageStateHandler?.getClineMessages?.() || [])]
+	const checkpointManagerErrorMessage = controller.task?.taskState?.checkpointManagerErrorMessage
+
+	const processedTaskHistory = (taskHistory || [])
+		.filter((item: any) => item.ts && item.task)
+		.sort((a: any, b: any) => b.ts - a.ts)
+		.slice(0, 100)
+
+	const latestAnnouncementId = getLatestAnnouncementId()
+	const shouldShowAnnouncement = lastShownAnnouncementId !== latestAnnouncementId
+	const platform = process.platform as Platform
+	const distinctId = getDistinctId()
+	const version = ExtensionRegistryInfo.version
+	const clineConfig = ClineEnv.config()
+	const environment = clineConfig.environment
+	const banners = BannerService.get().getActiveBanners() ?? []
+	const welcomeBanners = BannerService.get().getWelcomeBanners() ?? []
+
+	// Check OpenAI Codex authentication status
+	let openAiCodexIsAuthenticated = false
+	try {
+		const { openAiCodexOAuthManager } = await import("@/integrations/openai-codex/oauth")
+		openAiCodexIsAuthenticated = await openAiCodexOAuthManager.isAuthenticated()
+	} catch {
+		// Codex OAuth not available
+	}
+
+	return {
+		version,
+		apiConfiguration,
+		currentTaskItem,
+		clineMessages,
+		currentFocusChainChecklist: controller.task?.taskState?.currentFocusChainChecklist || null,
+		checkpointManagerErrorMessage,
+		autoApprovalSettings,
+		browserSettings,
+		focusChainSettings,
+		preferredLanguage,
+		mode,
+		strictPlanModeEnabled,
+		yoloModeToggled,
+		useAutoCondense,
+		subagentsEnabled,
+		userInfo,
+		mcpMarketplaceEnabled,
+		mcpDisplayMode,
+		telemetrySetting,
+		planActSeparateModelsSetting,
+		enableCheckpointsSetting: enableCheckpointsSetting ?? true,
+		platform,
+		environment,
+		distinctId,
+		globalClineRulesToggles: globalClineRulesToggles || {},
+		localClineRulesToggles: localClineRulesToggles || {},
+		localWindsurfRulesToggles: localWindsurfRulesToggles || {},
+		localCursorRulesToggles: localCursorRulesToggles || {},
+		localAgentsRulesToggles: localAgentsRulesToggles || {},
+		localWorkflowToggles: workflowToggles || {},
+		globalWorkflowToggles: globalWorkflowToggles || {},
+		globalSkillsToggles: globalSkillsToggles || {},
+		localSkillsToggles: localSkillsToggles || {},
+		remoteRulesToggles,
+		remoteWorkflowToggles,
+		shellIntegrationTimeout,
+		terminalReuseEnabled,
+		vscodeTerminalExecutionMode,
+		defaultTerminalProfile,
+		isNewUser,
+		welcomeViewCompleted,
+		onboardingModels,
+		mcpResponsesCollapsed,
+		terminalOutputLineLimit,
+		maxConsecutiveMistakes,
+		customPrompt,
+		taskHistory: processedTaskHistory,
+		shouldShowAnnouncement,
+		favoritedModelIds,
+		backgroundCommandRunning: controller.backgroundCommandRunning ?? false,
+		backgroundCommandTaskId: controller.backgroundCommandTaskId,
+		workspaceRoots: controller.workspaceManager?.getRoots?.() ?? [],
+		primaryRootIndex: controller.workspaceManager?.getPrimaryIndex?.() ?? 0,
+		isMultiRootWorkspace: (controller.workspaceManager?.getRoots?.()?.length ?? 0) > 1,
+		multiRootSetting: {
+			user: stateManager.getGlobalStateKey("multiRootEnabled"),
+			featureFlag: true,
+		},
+		clineWebToolsEnabled: {
+			user: stateManager.getGlobalSettingsKey("clineWebToolsEnabled"),
+			featureFlag: featureFlagsService.getWebtoolsEnabled(),
+		},
+		worktreesEnabled: {
+			user: stateManager.getGlobalSettingsKey("worktreesEnabled"),
+			featureFlag: featureFlagsService.getWorktreesEnabled(),
+		},
+		hooksEnabled: getHooksEnabledSafe(stateManager.getGlobalSettingsKey("hooksEnabled")),
+		lastDismissedInfoBannerVersion,
+		lastDismissedModelBannerVersion,
+		remoteConfigSettings: stateManager.getRemoteConfigSettings?.(),
+		lastDismissedCliBannerVersion,
+		dismissedBanners,
+		nativeToolCallSetting: stateManager.getGlobalStateKey("nativeToolCallEnabled"),
+		enableParallelToolCalling: stateManager.getGlobalSettingsKey("enableParallelToolCalling"),
+		backgroundEditEnabled: stateManager.getGlobalSettingsKey("backgroundEditEnabled"),
+		optOutOfRemoteConfig: stateManager.getGlobalSettingsKey("optOutOfRemoteConfig"),
+		doubleCheckCompletionEnabled,
+		lazyTeammateModeEnabled,
+		showFeatureTips,
+		banners,
+		welcomeBanners,
+		openAiCodexIsAuthenticated,
+	} as ExtensionState
+}
diff --git a/src/sdk/SdkController.ts b/src/sdk/SdkController.ts
new file mode 100644
index 0000000000..69936f8812
--- /dev/null
+++ b/src/sdk/SdkController.ts
@@ -0,0 +1,240 @@
+// Replaces classic src/core/controller/index.ts (see origin/main)
+//
+// This is the SDK-backed Controller. It provides the same interface as the
+// classic Controller but delegates to the Cline SDK (@clinebot/core).
+//
+// During migration, unimplemented methods log warnings. The extension will
+// compile and load, but functionality is added incrementally in Steps 4-8.
+
+import type { ModelInfo } from "@shared/api"
+import type { ChatContent } from "@shared/ChatContent"
+import type { ExtensionState } from "@shared/ExtensionMessage"
+import type { HistoryItem } from "@shared/HistoryItem"
+import type { McpMarketplaceCatalog } from "@shared/mcp"
+import type { Settings } from "@shared/storage/state-keys"
+import type { Mode } from "@shared/storage/types"
+import type { TelemetrySetting } from "@shared/TelemetrySetting"
+import type { UserInfo } from "@shared/UserInfo"
+import { StateManager } from "@/core/storage/StateManager"
+import { ClineExtensionContext } from "@/shared/cline"
+import { Logger } from "@/shared/services/Logger"
+
+/**
+ * Log a stub warning and return undefined.
+ */
+function stubWarn(name: string): void {
+	Logger.warn(`[SdkController] STUB: ${name} not yet implemented`)
+}
+
+export class Controller {
+	task?: any // Will be typed to SDK session when implemented in Step 4
+
+	mcpHub: any // Replaced by SDK MCP manager in Step 7
+	accountService: any // Replaced by SDK account service in Step 6
+	authService: any // Replaced by SDK auth in Step 6
+	ocaAuthService: any // Replaced by SDK auth in Step 6
+	readonly stateManager: StateManager
+
+	// Private state kept for stub compatibility
+	private backgroundCommandRunning = false
+	private backgroundCommandTaskId?: string
+
+	constructor(readonly context: ClineExtensionContext) {
+		// StateManager must be initialized before creating the Controller
+		this.stateManager = StateManager.get()
+
+		// Services will be properly initialized in later steps.
+		// For now, set to undefined so the extension compiles and loads.
+		this.mcpHub = undefined
+		this.accountService = undefined
+		this.authService = undefined
+		this.ocaAuthService = undefined
+
+		Logger.log("[SdkController] Initialized with SDK adapter layer")
+	}
+
+	async dispose(): Promise<void> {
+		await this.clearTask()
+		this.mcpHub?.dispose?.()
+		Logger.log("[SdkController] Disposed")
+	}
+
+	async handleSignOut(): Promise<void> {
+		stubWarn("handleSignOut")
+		await this.postStateToWebview()
+	}
+
+	async handleOcaSignOut(): Promise<void> {
+		stubWarn("handleOcaSignOut")
+		await this.postStateToWebview()
+	}
+
+	async setUserInfo(_info?: UserInfo): Promise<void> {
+		stubWarn("setUserInfo")
+	}
+
+	// ---- Task lifecycle (Step 4) ----
+
+	async initTask(
+		_task?: string,
+		_images?: string[],
+		_files?: string[],
+		_historyItem?: HistoryItem,
+		_taskSettings?: Partial<Settings>,
+	): Promise<string | undefined> {
+		stubWarn("initTask")
+		return undefined
+	}
+
+	async reinitExistingTaskFromId(_taskId: string): Promise<void> {
+		stubWarn("reinitExistingTaskFromId")
+	}
+
+	async cancelTask(): Promise<void> {
+		stubWarn("cancelTask")
+	}
+
+	async cancelBackgroundCommand(): Promise<void> {
+		stubWarn("cancelBackgroundCommand")
+	}
+
+	async clearTask(): Promise<void> {
+		stubWarn("clearTask")
+	}
+
+	async handleTaskCreation(_prompt: string): Promise<void> {
+		stubWarn("handleTaskCreation")
+	}
+
+	// ---- Mode switching (Step 8) ----
+
+	async toggleActModeForYoloMode(): Promise<boolean> {
+		stubWarn("toggleActModeForYoloMode")
+		return false
+	}
+
+	async togglePlanActMode(_modeToSwitchTo: Mode, _chatContent?: ChatContent): Promise<boolean> {
+		stubWarn("togglePlanActMode")
+		return false
+	}
+
+	// ---- Telemetry ----
+
+	async updateTelemetrySetting(telemetrySetting: TelemetrySetting): Promise<void> {
+		await this.stateManager.setGlobalState("telemetrySetting", telemetrySetting as any)
+		await this.postStateToWebview()
+	}
+
+	// ---- Auth callbacks (Step 6) ----
+
+	async handleAuthCallback(_customToken: string, _provider: string | null = null): Promise<void> {
+		stubWarn("handleAuthCallback")
+		await this.postStateToWebview()
+	}
+
+	async handleOcaAuthCallback(_code: string, _state: string): Promise<void> {
+		stubWarn("handleOcaAuthCallback")
+		await this.postStateToWebview()
+	}
+
+	async handleMcpOAuthCallback(_serverHash: string, _code: string, _state: string | null): Promise<void> {
+		stubWarn("handleMcpOAuthCallback")
+	}
+
+	// ---- MCP marketplace (Step 7) ----
+
+	async refreshMcpMarketplace(_sendCatalogEvent: boolean): Promise<McpMarketplaceCatalog | undefined> {
+		stubWarn("refreshMcpMarketplace")
+		return undefined
+	}
+
+	// ---- Provider auth callbacks (Step 6) ----
+
+	async handleOpenRouterCallback(_code: string): Promise<void> {
+		stubWarn("handleOpenRouterCallback")
+	}
+
+	async handleRequestyCallback(_code: string): Promise<void> {
+		stubWarn("handleRequestyCallback")
+	}
+
+	async handleHicapCallback(_code: string): Promise<void> {
+		stubWarn("handleHicapCallback")
+	}
+
+	async readOpenRouterModels(): Promise<Record<string, ModelInfo> | undefined> {
+		stubWarn("readOpenRouterModels")
+		return undefined
+	}
+
+	// ---- Task history (Step 4) ----
+
+	async getTaskWithId(_id: string): Promise<{
+		historyItem: HistoryItem
+		taskDirPath: string
+		apiConversationHistoryFilePath: string
+		uiMessagesFilePath: string
+		contextHistoryFilePath: string
+		taskMetadataFilePath: string
+		apiConversationHistory: any[]
+	}> {
+		stubWarn("getTaskWithId")
+		return undefined as any
+	}
+
+	async exportTaskWithId(_id: string): Promise<void> {
+		stubWarn("exportTaskWithId")
+	}
+
+	async deleteTaskFromState(_id: string): Promise<HistoryItem[]> {
+		stubWarn("deleteTaskFromState")
+		return []
+	}
+
+	async updateTaskHistory(_item: HistoryItem): Promise<HistoryItem[]> {
+		stubWarn("updateTaskHistory")
+		return []
+	}
+
+	// ---- Background command state ----
+
+	updateBackgroundCommandState(running: boolean, taskId?: string): void {
+		this.backgroundCommandRunning = running
+		this.backgroundCommandTaskId = taskId
+	}
+
+	// ---- State management ----
+
+	async postStateToWebview(): Promise<void> {
+		// Import dynamically to avoid circular deps
+		const { sendStateUpdate } = await import("@core/controller/state/subscribeToState")
+		const state = await this.getStateToPostToWebview()
+		await sendStateUpdate(state)
+	}
+
+	async getStateToPostToWebview(): Promise<ExtensionState> {
+		// Delegate to the classic implementation which reads from StateManager.
+		// This will be gradually replaced with SDK-sourced state in Steps 4-8.
+		// For now, we import the classic getStateToPostToWebview logic.
+		try {
+			const { getStateToPostToWebview: classicGetState } = await import("@core/controller/state/getStateToPostToWebview")
+			return await classicGetState({
+				task: this.task,
+				stateManager: this.stateManager,
+				mcpHub: this.mcpHub,
+				backgroundCommandRunning: this.backgroundCommandRunning,
+				backgroundCommandTaskId: this.backgroundCommandTaskId,
+			})
+		} catch {
+			// Fallback: return minimal state if classic impl not available
+			return {} as unknown as ExtensionState
+		}
+	}
+
+	// ---- Workspace (kept from classic) ----
+
+	async ensureWorkspaceManager(): Promise<any> {
+		stubWarn("ensureWorkspaceManager")
+		return undefined
+	}
+}
diff --git a/src/sdk/index.ts b/src/sdk/index.ts
new file mode 100644
index 0000000000..5df339cc9e
--- /dev/null
+++ b/src/sdk/index.ts
@@ -0,0 +1,8 @@
+// SDK Adapter Layer
+// Replaces classic src/core/controller/ (see origin/main)
+//
+// This module provides the SDK-backed Controller and related adapters.
+// The webview continues to communicate via gRPC; this layer translates
+// between gRPC handlers and SDK calls.
+
+export { Controller } from "./SdkController"
diff --git a/vitest.config.sdk.ts b/vitest.config.sdk.ts
new file mode 100644
index 0000000000..e7f15f1b52
--- /dev/null
+++ b/vitest.config.sdk.ts
@@ -0,0 +1,20 @@
+import path from "node:path"
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+	test: {
+		include: ["src/sdk/**/*.test.ts"],
+		environment: "node",
+	},
+	resolve: {
+		alias: {
+			"@": path.resolve(__dirname, "src"),
+			"@core": path.resolve(__dirname, "src/core"),
+			"@integrations": path.resolve(__dirname, "src/integrations"),
+			"@services": path.resolve(__dirname, "src/services"),
+			"@shared": path.resolve(__dirname, "src/shared"),
+			"@utils": path.resolve(__dirname, "src/utils"),
+			"@packages": path.resolve(__dirname, "src/packages"),
+		},
+	},
+})